Русский
Українська
Հայերեն
ქართული
Қазақша
Español
Français
Deutsch
Italiano
فارسی
Article focus
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.
Mandatory website requirements for VPOS
Before production review, the site should already publish legal pages, prices, contacts and language versions.
A payment integration can be technically ready and still fail review if the website does not show the required merchant information and customer rules. Prepare these pages before test payment evidence and production access request.
If the product or service cannot be cancelled or refunded, state this clearly in the cancellation and refund policy. For Armenia, the Armenian website version is mandatory; when other languages exist, the same information should be present there as well.
- privacy policy;
- personal data processing policy;
- cancellation and refund policy, including non-refundable rules;
- Terms and Conditions: sale, delivery or service provision terms;
- prices for goods or services before payment;
- contact details: phone, e-mail, messengers or another working channel;
- Armenian website version and the same information in every available language.
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.
