Ключевые темы
Связанные публичные страницы
Если нужен не только разбор, а страница продукта, API или операционного сценария, начните с этих разделов VPOS.am.
Ecwid payment app начинается с правильного paymentUrl
PaymentUrl должен принимать запрос магазина, создавать payment session и безопасно отправлять клиента в checkout.
В Ecwid пользователь выбирает платежный метод, а storefront отправляет платежный запрос на paymentUrl приложения. Этот endpoint не должен просто пересылать браузер дальше. Он должен разобрать запрос, проверить обязательные поля и создать контролируемую payment session.
Минимально нужно сохранить store id, order id, reference transaction id, сумму, валюту, returnUrl и внутренний payment id. Тогда повторный submit, закрытая вкладка или задержанный callback не превращаются в потерянный заказ.
- принимать encrypted payment request только на backend;
- создавать одну payment session на один reference transaction;
- сохранять оригинальный Ecwid order id в metadata;
- не помечать заказ paid до подтвержденного платежа.
Почему важны idempotency и provider-safe order id
Ecwid order id и provider order id могут иметь разные ограничения, поэтому платежный слой должен хранить стабильную связь.
Платежный провайдер может ограничивать длину или формат номера заказа. Поэтому безопаснее создать compact provider reference, а исходный Ecwid order id сохранить во внутренней metadata и журнале событий.
Idempotency нужна, чтобы повторный запрос от Ecwid не создал вторую независимую оплату. Backend должен вернуть уже созданную payment session или аккуратно создать новую payment attempt, если это разрешено правилами магазина.
- связывать Ecwid order id, provider reference и payment id;
- использовать idempotency key для повторного submit;
- не хранить raw tokens в логах;
- логировать request id и ошибку валидации без секретов.
Как возвращать клиента и обновлять статус заказа
ReturnUrl полезен для UX, но paid-статус должен появляться только после server-side подтверждения.
После оплаты провайдер возвращает клиента, но браузерный return не гарантирует финальный статус. Надежный flow сначала проверяет provider callback или status check, обновляет внутреннюю payment session, синхронизирует Ecwid order status и только потом возвращает клиента в storefront.
Если Ecwid status sync временно не прошел, платеж нельзя терять. Нужно сохранить verified paid, поставить повторную синхронизацию и показать оператору исключение после нескольких неуспешных попыток.
- обновлять Ecwid order status только после verified paid;
- различать paid, pending, failed, cancelled и refunded;
- повторять временные ошибки Ecwid API;
- включать Ecwid-заказы в ежедневную сверку.
FAQ
Можно ли обновлять Ecwid-заказ сразу после returnUrl?
Лучше нет. ReturnUrl нужен для возврата клиента в магазин, но paid-статус должен ставиться после server-side проверки платежа или доверенного provider callback.
Что делать, если Ecwid отправил платежный запрос повторно?
Использовать idempotency key по store id и reference transaction id. Повторный submit должен вернуть существующую payment session или контролируемо создать новую попытку.
Можно ли хранить Ecwid token в открытом виде?
Нет. Токены и секреты нельзя писать в логи или metadata в открытом виде. Если токен нужен для sync, его нужно хранить зашифрованно и ограничить доступ.
