> For the complete documentation index, see [llms.txt](https://docs.ecwid.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ecwid.com/guides/payments/process-online-payment-requests/step-1.-decode-and-parse-payment-request-from-ecwid.md).
# Step 1. Decode and parse payment request from Ecwid
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.
Encoded request example
```html
```
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 [app dashboard page](https://my.ecwid.com/#develop-apps).
After decoding, you can access order details in the `enc_data` JSON object.
Request decoding examples in PHP and NodeJS:
{% tabs %}
{% tab title="PHP" %}
```php
decoded: $decoded";
// 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 = "QKJkxLNKSu22POC5UzxTBMoUQolefDPs"; // App's client_secret
// The resulting JSON array will be in $result variable
$result = getEcwidPayload($client_secret, $ecwid_payload);
?>
```
{% endtab %}
{% tab title="NodeJS" %}
```n4js
var crypto = require("crypto");
var EncryptionHelper = (function () {
function decryptText(cipher_alg, key, text, encoding) {
const bText = Buffer.from(text, encoding);
const iv = bText.subarray(0, 16);
const tag = bText.subarray(-16)
const payload = bText.subarray(16, -16);
const decipher = crypto.createDecipheriv(cipherAlg, key, iv);
decipher.setAuthTag(tag);
return Buffer.concat([
decipher.update(payload),
decipher.final()
]);
}
return {
decryptText: decryptText
};
})();
module.exports = EncryptionHelper;
let client_secret = 'QKJkxLNKSu22POC5UzxTBMoUQolefDPs'; // App's client_secret
let data = req.body.enc_data;
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);
```
{% endtab %}
{% endtabs %}
If you are using C# language, create additional padding to make the payload a multiple of 4:
```csharp
base64 = base64.PadRight(base64.Length + (4 - (base64.Length % 4)), '=');
```
Decoded request example
```json
{
storeId: 42722912,
returnUrl: 'https://app.ecwid.com/custompaymentapps/42722912?orderId=5***6&clientId=custom-app-***-2×tamp=1752226448902&key=4***a',
merchantAppSettings: {},
cart: {
currency: 'USD',
order: {
id: 'Q7WML',
orderNumber: 5***6,
vendorOrderNumber: 'Q7WML',
email: 'nikita.miroshnichenko@lightspeedhq.com',
ipAddress: '188.169.99.36',
hidden: false,
createDate: '2025-07-11 09:33:40 +0000',
createTimestamp: 1752226420,
updateDate: '2025-07-11 09:34:08 +0000',
updateTimestamp: 1752226448,
refererUrl: 'https://milterstore.company.site/products/',
globalReferer: 'https://milterstore.company.site/',
additionalInfo: {
ga4_client_id: '1987434357.1751162187',
ga4_session_id: '1752226323',
google_customer_id: '1987434357.1751162187'
},
extraFields: {
ecwid_order_delivery_time_display_format: 'DATETIME',
ecwid_order_delivery_time_interval_end: '2025-07-30 22:30:00 +0000',
ecwid_order_delivery_time_interval_start: '2025-07-30 22:00:00 +0000',
wdzklbo: '16:00 - 16:30'
},
orderExtraFields: [
{
customerInputType: 'DATETIME',
title: '',
id: 'ecwid_order_delivery_time_interval_end',
value: '2025-07-30 22:30:00 +0000',
orderDetailsDisplaySection: '',
orderBy: '0'
},
{
customerInputType: 'TEXT',
title: '',
id: 'ecwid_order_delivery_time_display_format',
value: 'DATETIME',
orderDetailsDisplaySection: '',
orderBy: '0'
},
{
customerInputType: 'SELECT',
title: 'Time selection',
id: 'wdzklbo',
value: '16:00 - 16:30',
orderDetailsDisplaySection: 'shipping_info',
orderBy: '1'
},
{
customerInputType: 'DATETIME',
title: 'Delivery date and time',
id: 'ecwid_order_delivery_time_interval_start',
value: '2025-07-30 22:00:00 +0000',
orderDetailsDisplaySection: 'shipping_info',
orderBy: '2'
}
],
orderComments: '',
fulfillmentStatus: 'AWAITING_PROCESSING',
externalFulfillment: false,
paymentStatus: 'INCOMPLETE',
paymentMethod: 'Test Payment Method',
paymentModule: 'CUSTOM_PAYMENT_APP-custom-app-***-2',
paymentParams: {},
referenceTransactionId: 'transaction_571937036',
ticket: 2062523945,
acceptMarketing: false,
giftCardRedemption: 0,
totalBeforeGiftCardRedemption: 265.3,
giftCardDoubleSpending: false,
total: 265.3,
totalWithoutTax: 236.87,
subtotal: 240.3,
subtotalWithoutTax: 214.55,
usdTotal: 265.3,
tax: 28.43,
customerTaxExempt: false,
customerTaxId: '',
customerTaxIdValid: false,
reversedTaxApplied: false,
couponDiscount: 0,
volumeDiscount: 0,
membershipBasedDiscount: 0,
totalAndMembershipBasedDiscount: 0,
discount: 0,
discountInfo: [],
items: [
{
id: 2034647007,
productId: 591363296,
categoryId: 0,
price: 80.1,
productPrice: 80.1,
isCustomerSetPrice: false,
priceWithoutTax: 71.52,
shipping: 25,
tax: 28.43,
fixedShippingRate: 0,
sku: '00010',
name: 'testProduct91',
nameTranslated: { de: '', en: 'testProduct91' },
shortDescription: '',
shortDescriptionTranslated: { de: '', en: '' },
quantity: 3,
quantityInStock: 31,
weight: 0,
imageUrl: 'https://d2j6dbq0eux0bg.cloudfront.net/images/42722912/4082575898.png',
smallThumbnailUrl: 'https://d2j6dbq0eux0bg.cloudfront.net/images/42722912/4082575900.png',
hdThumbnailUrl: 'https://d2j6dbq0eux0bg.cloudfront.net/images/42722912/4082575901.png',
isShippingRequired: true,
trackQuantity: true,
fixedShippingRateOnly: false,
digital: false,
productAvailable: true,
couponApplied: false,
giftCard: false,
selectedOptions: [
{
name: 'Color',
nameTranslated: { de: 'Farbe', en: 'Color' },
type: 'SWATCH_CHOICE',
value: 'Red',
valueTranslated: { de: '', en: 'Red' },
valuesArray: [ 'Red' ],
selections: [
{
selectionTitle: 'Red',
selectionModifier: 0,
selectionModifierType: 'ABSOLUTE'
}
]
}
],
taxable: true,
taxes: [
{
name: 'test tax',
value: 12,
total: 28.43,
taxOnDiscountedSubtotal: 25.75,
taxOnShipping: 2.68,
includeInPrice: true
}
],
dimensions: { length: 0, width: 0, height: 0 },
discountsAllowed: true
}
],
shippingPerson: {
name: 'First Last',
firstName: 'First',
lastName: 'Last',
companyName: 'Test',
street: 'Example st.',
city: 'San Diego',
countryCode: 'US',
countryName: 'United States',
postalCode: '92007',
stateOrProvinceCode: 'CA',
stateOrProvinceName: 'California',
phone: '0123456789'
},
shippingOption: {
shippingMethodName: 'Local delivery – TEST 20',
shippingRate: 25,
shippingRateWithoutTax: 22.32,
isPickup: false,
fulfillmentType: 'DELIVERY'
},
taxesOnShipping: [ { name: 'test tax', value: 12, total: 2.68 } ],
handlingFee: {
name: 'Handling Fee',
value: 0,
valueWithoutTax: 0,
description: '',
taxes: []
},
shipments: [],
customSurcharges: [],
refundedAmount: 0,
refunds: [],
predictedPackage: [],
pricesIncludeTax: true,
disableAllCustomerNotifications: false,
externalOrderData: {},
shippingLabelAvailableForShipment: false,
electronicInvoicePecEmail: '',
electronicInvoiceSdiCode: '',
commercialRelationshipScheme: 'b2c'
}
},
token: 'secret_F***c',
lang: 'en'
}
```
Quickstart with the [payment integration template](/guides/payments/sample-payment-app.md) (outdated).
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): .
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.ecwid.com/guides/payments/process-online-payment-requests/step-1.-decode-and-parse-payment-request-from-ecwid.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.