When a customer proceeds to payment from the Ecwid checkout, Ecwid API sends a unique payment request to the endpoint of an app assigned to the chosen payment method.
After receiving a new payment request from Ecwid on your paymentUrl endpoint, the first step is to decode and parse it. All payment requests are encoded and contain all the order data, which is essential for further steps.
What happens on the storefront
Upon clicking the “Go to Payment” button, a customer is redirected to your app paymentUrl. For now, you can’t do anything with the storefront, so we recommend showing a loading placeholder until further steps.
What happens on the backend
The paymentUrl endpoint of your app receives a POST request with encoded data in the request body.
The initial request with the order data coming to your paymentUrl is encrypted with an AES-128 mechanism in GCM mode (aes-128-gcm).
The key for decoding is the first 16 characters of your app’s unique and unchangeable client_secret. Get your clent_secret value from the .
After decoding, you can access order details in the enc_data JSON object.
Request decoding examples in PHP and NodeJS:
<?php
function getEcwidPayload($app_secret_key, $data) {
// Get the encryption key (16 first bytes of the app's client_secret key)
$encryption_key = substr($app_secret_key, 0, 16);
// Decrypt payload
$json_data = aes_128_decrypt($encryption_key, $data);
// Decode json
$json_decoded = json_decode($json_data, true);
return $json_decoded;
}
function aes_128_decrypt($key, $data) {
// Ecwid sends data in url-safe base64. Convert the raw data to the original base64 first
$base64_original = str_replace(array('-', '_'), array('+', '/'), $data);
// Get binary data
$decoded = base64_decode($base64_original);
echo "<div>decoded: $decoded</div>";
// Initialization vector is the first 16 bytes of the received data
$iv = substr($decoded, 0, 16);
// Tag is the last 16 bytes of the received data
$tag = substr($decoded, -16);
// The payload itself is the rest of the received data
$payload = substr($decoded, 16, -16);
// Decrypt raw binary payload
$json = openssl_decrypt($payload, "aes-128-gcm", $key, true, $iv, $tag);
return $json;
}
// Get payload from the POST and process it
$ecwid_payload = $_POST['enc_data'];
$client_secret = "payment-app-secret-key"; // This is a dummy value. Place your client_secret key here. You received it from Ecwid team in email when registering the app
// The resulting JSON array will be in $result variable
$result = getEcwidPayload($client_secret, $ecwid_payload);
?>
var crypto = require("crypto");
var EncryptionHelper = (function () {
function decryptText(cipher_alg, key, text, encoding) {
var bText = Buffer.from(text, encoding);
var iv = bText.slice(0, 16);
var tag = bText.slice(-16)
var payload = bText.slice(16, -16);
var decipher = crypto.createDecipheriv(cipher_alg, key, iv);
decipher.setAuthTag(tag);
return Buffer.concat([
decipher.update(payload, encoding),
decipher.final()
]);
}
return {
decryptText: decryptText
};
})();
module.exports = EncryptionHelper;
let client_secret = 'CLIENT SECRET';
let data = 'ECWID PAYLOAD'
let encryption_key = client_secret.substr(0, 16);
var originalBase64 = data.replace(/-/g, "+").replace(/_/g, "/");
var decrypted = EncryptionHelper.decryptText("aes-128-gcm", encryption_key, originalBase64, "base64");
var payloadObject = JSON.parse(decrypted);
If you are using C# language, create additional padding to make the payload a multiple of 4:
If you want to use Web Cryptography API / SublteCrypto for decoding payment requests, check out the code example created by our community developers (may be partially outdated due to encryption mechanism changes): .
