Key topics
Related public pages
If you need the product, API or operations page rather than only the article, start with these VPOS.am sections.
Ecwid payment app starts with the right paymentUrl
PaymentUrl should receive the store request, create a payment session and send the customer to checkout safely.
In Ecwid, the customer chooses a payment method and the storefront sends a payment request to the app paymentUrl. This endpoint should not just redirect the browser. It should parse the request, validate required fields and create a controlled payment session.
At minimum, store store id, order id, reference transaction id, amount, currency, returnUrl and internal payment id. Then repeated submit, closed tab or delayed callback does not become a lost order.
- receive encrypted payment request only on backend;
- create one payment session for one reference transaction;
- store original Ecwid order id in metadata;
- do not mark order paid before verified payment.
Why idempotency and provider-safe order id matter
Ecwid order id and provider order id can have different limits, so the payment layer should keep a stable mapping.
A payment provider may limit length or format of the order number. A safer approach is to create a compact provider reference and keep original Ecwid order id in internal metadata and event log.
Idempotency prevents repeated Ecwid requests from creating a second independent payment. Backend should return the existing payment session or create a new payment attempt only if store rules allow it.
- connect Ecwid order id, provider reference and payment id;
- use idempotency key for repeated submit;
- do not store raw tokens in logs;
- log request id and validation error without secrets.
How to return customer and update order status
ReturnUrl is useful for UX, but paid status should appear only after server-side confirmation.
After payment, the provider returns the customer, but browser return does not guarantee final status. Reliable flow first verifies provider callback or status check, updates internal payment session, syncs Ecwid order status and only then returns customer to storefront.
If Ecwid status sync temporarily fails, payment must not disappear. Store verified paid, retry sync and show an operator exception after repeated failures.
- update Ecwid order status only after verified paid;
- separate paid, pending, failed, cancelled and refunded;
- retry temporary Ecwid API errors;
- include Ecwid orders in daily reconciliation.
FAQ
Can Ecwid order be updated immediately after returnUrl?
Prefer not. ReturnUrl sends the customer back to the store, but paid status should be set after server-side payment verification or trusted provider callback.
What if Ecwid sends the payment request again?
Use an idempotency key based on store id and reference transaction id. Repeated submit should return the existing payment session or create a controlled new attempt.
Can Ecwid token be stored in plain text?
No. Tokens and secrets should not be written to logs or metadata in plain text. If token is needed for sync, store it encrypted and restrict access.
