Order status and customer return

Update order status

For Ecwid to find out the result of the payment, your application must update the order status before returning them back to the storefront. To update order status, you will need these details: reference transaction id, store ID and access token. All of these details are provided in a Payment request to your application's payment URL once you decrypt it.

PUT /api/v3/4870020/orders/transaction_55885213 HTTP/1.1
Host: app.ecwid.com
Authorization: Bearer secret_abc123...efg
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

{
    "paymentStatus": "PAID"
}

<?php

$token = "secret_abc123...efg"
$url = "https://app.ecwid.com/api/v3/4870020/orders/transaction_55885213";
$data = array('paymentStatus'=>'PAID');
$data_json = json_encode($data);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json','Content-Length: ' . strlen($data_json),'Authorization: Bearer ' . $token));
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_json);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response  = curl_exec($ch);
curl_close($ch);

?>

Fields:

• referenceTransactionId field in the cart object of a request body
• storeId field in the request body
• token field in the request header

Once the order is updated with correct status, your app should return the customer back to the store.

📘

In case of failed/cancelled transactions, we do recommend responding with the "INCOMPLETE" payment status

Return customer to storefront

When a customer is finished making their payment for an order, your app needs to return them back to the storefront.

returnUrl is a field provided in a request from Ecwid. Its value is a destination, where your app should return the customer to after the payment process is complete. After user is directed to that page, Ecwid will check that order and depending on its status, the action will be different:

• If the order is in PAID or AWAITING_PAYMENT payment status, customer's cart will be cleared and they will see 'Thank you for your order' page
• for any other payment status (like INCOMPLETE and CANCELLED), customer will see the payment selection page in store checkout

📘

Before returning customer to storefront, make sure to update the order payment status first. This way Ecwid will be able to show relevant content to customers at all times.

Showing custom payment message

You have an option to provide a custom error message when returning customer to storefront. It is done via errorMsg query parameter of the return URL.

Return URL example:
https://example.com/123456?clientId=client_id

Add custom error message text for customer:
https://example.com/123456?clientId=client_id&errorMsg=My%20error%20message

Error message language

When Ecwid makes a payment request to your URL, it also sends the storefront's language in that data. Use it to show the error message in the relevant language:

{
	"storeId": 1003,
	"lang": "fr",
	"returnUrl": "https://example.com/123456?clientId=mollie-pg",
	"cart": {...}
}