NAV

Processing payment request

Request details

Encoded request from Ecwid example

POST https://mycoolapp.com/integration HTTP/1.1
<form action="https://mycoolapp.com/integration" method="POST" accept-charset='utf-8'>
<input type='hidden' name='data' value="u2D5lOdpstoEc9W9r5Jqdoth0bMMqqfo9eFouhpUVeSondZqlTVGrW13vFujYHjQlm5H8WU1E1Qu1Fr6-YehYtj4W9Jkt6se-KzJ1FEZHCsv_Qp_hfRoysvOlzJCh8kw5tmOdhesRJnXs8ITVEVP4PGMPteytrKrBDPdF0f4IPYd3lnyp-3SzH-dnixtDMlzszaXy29nYxAr7D2EkgL_DBT5vW-uWm0it_K1fCmGFjCvAHxYbwjNhyRRLP_W5LB0PGhSVYxpyGqLD757zahu__rAwqSSKpew1FSX383nF6Q5BffWdUoG_zmHLYlCxsyv0c_sSw4n5IwiPxwQatie3ibLiro-6GpN6LBNzywewptA8u_Smgup4KmI9qBsywxgGCY7BAeFR5gLoxY147ZXv1Hnganjk79xDIruEN3pqgca4-mfaEJjQIAcuDxmd6Twy9BPUTGFIgnEWUfbief44ZKgG41N5fkqSMmAScBN1LYMuMj9BOME0DH6iho-txy3YgRrCPQgqxSRe2-ytKC6chXfwvWdWs5rQz7Jctl9S6Iobp_whWk6hV8xY1QxpujJP2kOnX9ysMpcmt2aCP1ES6kXPzDr1Y9u4cxnepgagX2Jth9j41mO5e4C-AYdTRFndMMSBkp6r4RvpA64cULBMJLbAD6eI4A4zqmTQR4PJ4s7eyvvlmkPFSnN0PMOn2WO9qsFweLAztTp6neuiECUvsELWPj20UY49Z5idejOmXsq5SAPdv7iDnEBEjIxY2xrgAQ6R5baGo8UtCmA2rfgROCx1UiMViCU5XjIBibI09NqYJxKCTrXGShANsZpigwssc8i3DxxWQJY7D7Axo8AYIBRqFhtssAU00iF2Xqn5Sa3Mzcf5Z4onA0RdLf9bOkKNijik5bt4vVHRxk89O-mhp2vS2o78WYhw8cf4R3DiiTaSvKzJi6DtKgIeJAxuvL5Iw1UDSQkC8GfRXRdXfDvG2cCmmWrNJgIfY8pDZEedsSEBxJN-5-hcajkc3Naf-QCj6WioljyVt8Pm090SLdxUEyZhKUegF9zz78ZXEWBQfUdKvqDVopPxwba5nbrwjaMKompDELrqBAViALX_9_IFriq7Jt3tMIQX2JdVJFfyTWJ3LJefDTZUmadEVc96yBN2AawIhGXpUwp-86PZmHgrB-A_ehvhovsP6mdINPs_iV822ft86wlG7lOivKGfjhUmtL8CBJh1bC11QRkUxDJhm3oXFlBISzwv_hOlMYG3DAPasjPb80rEWR7hYy3fe4BzCQozER40OJ0-z2eXkXSAY0r2kyW62jtdiKnO-MwWRvZ7rqYjpSpJA7nLcRULpjiXEGcvs5GGdJcZ7KKrFWC6UTFvamWmz9KUG7Mr_ENmbCqUs9J5WBAj6DlpFPONU54omrOQTk3qhD6lyPzVlazIteoE3Yh-r0kPaWBZZPk1vhWkM6rX4w5z1UDNWYAGOPUSpfLlsV5_AqBjn3BqMkM0gjGn72hYWNX6xdb1fLMq_mH_imaaUrk0Xmpt9ZcqSPo2oHmP93RQZQ5CcKl-G3YC8H0s0Mt5pZarJLDJwrwaQC35V8zkaASB-AKBETcqh7f_7vGD8FasDpJBGD3Aoln615Nh31VzIhPy4hwW2EwDD8Gz2R2OLpuzlkV7gxnytmBWD08KTfdaiPKBXfWZS651ggBWB_ZLTEez1uFCuIDjJf3kJb2US77sU7ov8CJcRau4k92vgSFoY8QQGUPo9wjYRs1VOP05c0UXLLf6IRQ0q8b0uZUqF6hleLqC2FKpTw_8Yx3lHXUzg7zYUWpnBRktbDc64kSnmr3Qwq1MNuwz7iU2k3alOuD9WMxA8NRd4RIEWNFt333wqmPwKqEWtR0faVLldhUIwi2lBygqwFAIP-Bb5a0fOXL6ahiYVgli8CFU_3BnvCgH1C4zbO1tXhdNMhLyH4l97v7F5TPs8iIminifBgWVztDJsmtEUDjmc_AUUjaNbqw3KPGt6KYGYZB1m-JTdwQhm189OZx2KnnurMiEZHjaggxIeVX8H_8ZjK9xssuOrtQwV4XYyWSTjzllxVPyi15qzZvlMkwATi_BoFO_Uktd9DmkhX2M01tn_j3lipWegcgFcml-oODVQuqQQYkCuA9Se1vx0o8ocxpBpY220gy_E3Osp4cI-GX56ldB8wa3-keD930OXBTj9fWI4iVc7nMLmdIYmRZajc7UMcQq0C_BNSfEYpxxxasMgtIHGQ-Qp6r_KcwPJd2HungtBqsY4QdjFAwhugZfrRqBWs4vbmNUbAYArMwjQLGqRGStDIQ563IdfGmzyIf9cKSqFvJL2nHlgPs5_DRZH9vnK1L8lZImJoakq7mLD8AJJHlZ2lyS2Xaqi5q-b9uzN-DiZCZ15BQVEQ851q1ftwwVZdU2X6Cdl4B0uEweeigGFc1R6ArhGk8cu7FeNve25FonEbK_9Ts0qdJfWEQ0xvVneTYzQgM23hZPcCMNCp6LTswXFW-71ca3ReXLELxPoT0tiRm1iwjSWPg_QQ1kLZ3mKlhKTH--whU8fVtoVBRBccsQpWuyNW6i9usRDgHwGW2se73qV5PDhtvwA8Wshf4fiOxl-akOvAcfRK0l_Z52YiVfLcZ2yFszwy59jVol5In9W0iDzmgRse1LNubavQ4iCvdgLnjfn8niCCZO8ymUE2-1TondrOIfpWqq6yyezgZoMlXgquttgGValadzXbiR12cyvJpqDU6YkxDJlwUqGydfZ4PSuOuJyBXrzw3dRIrC3H8lEcGq0LCBRs_tFKBR8JgZiHcT43HhDL9fs2BA59QTi_gR75S3PRVNspXZWz56rUkPBnImzcYrTUAJh0xNpURNpv__RbpYJmE1chOsYoGTLHyljl2CTnN_MoJM8Aw8FWbJZJSc77LBIlj-SXOqvHfJCjRGwx3KptOnrZPSbIM45HRgX1HGhp4MYlZGIPchMJNlguwhGzW2_E_UnXMpNtHFhN5-_nYVRUP8Q8t9YY2cNvZolgy0tm0Gr87JOlGJjpu85Hi0vrYwiB47ot52W94Jn2TbziuODM7a-3kt0tF3utrdfOc6vewoTiImk9UK1TKxi7NAioyZhbxJu3Rp9U5dgK0Egsf2U8gTT9_F0CVpLxelye9DFArnDXpLmoya0uGxX10yZCHfeUa0M44BFFRJh046r_rL1MBVZ9cLcsrAFPXrHIO3vPgVe7gzM7HC-2aN9q-qsVym85tLrdK7fc5QkroeBd5JcXiuNikFD__7x7yKx7hPpqjBOHDkLUSZmBCOLlwiwu-whPI-gl3kG2lxyuvzKfj_lI_EwdEYfPRAFb6AGaD7iN3ytwi34MGRCp2WrUmSNzYOECGdZrECUgIwsqvB06Xk6URc7QMvlk5ewEdvoy2wxIFbu1RX-bNq7jvWvE5qLwmvBizybffIZhRSPxe1HkrqvC8lqaXl5TVMBFMfjuIeSsEEFxgaBEKLrH3CQc__vlEJF6AelXwJi1IYOFGratDV4gmY0LNqLc0XLMUuruE-4jtI7NCAtnZQ2LKG7YD3fMqcAcukjEaKSCo2Pknt1ldcanX5raCE4oYh--AD85Rbtwc52nX0CeX2rnRU6jx40eujusktUb7UXWURvttpoocIH-tqmbSuawNFNlIjagft0wVhzhXF1UewGzRnDHV1yJCo9X8Oe7ln_2unSsdh7ziblt4C5_5yFPvyF6WgMzP2YuCpW9JRXUq9oWYHLUIzGjqW9cx74nZxsJWaG880-8QzRVrSuC6ExYWcQiK3gppWToxgm1xTUumeqJm5dDa6hdytAQ6DC9BzNlRCLhhWMGoUOWFid1aNw__DRO2G_y9O3jdaaT1cD5FuQ"/>
</form>

Decoding the request to get order details

<?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);

  // Initialization vector is the first 16 bytes of the received data
  $iv = substr($decoded, 0, 16);

  // The payload itself is is the rest of the received data
  $payload = substr($decoded, 16);

  // Decrypt raw binary payload
  $json = openssl_decrypt($payload, "aes-128-cbc", $key, OPENSSL_RAW_DATA, $iv);
  //$json = mcrypt_decrypt(MCRYPT_RIJNDAEL_128, $key, $payload, MCRYPT_MODE_CBC, $iv); // You can use this instead of openssl_decrupt, if mcrypt is enabled in your system

  return $json;
}

// Get payload from the POST and process it
$ecwid_payload = $_POST['data'];
$client_secret = "payment-app-secret-key"; // this is a dummy value. Please place your app secret key here

// The resulting JSON array will be in $result variable
$result = getEcwidPayload($client_secret, $ecwid_payload);
?>

When customer tries to pay with your payment method, Ecwid will send a POST request with a format as described on the right.

The value of the data input is encoded with a AES-128 mechanism, where the first 16 characters is the client_secret of your application, which serves as a key to the decoding process. To find out more on how to decode the value, see the example code in Step #1 of Server-side Native Apps section.

Decoded request from Ecwid example

{
    "storeId": 41002,
    "returnUrl": "https://mdemo.ecwid.com/?orderId=106002&clientId=payment-integration",
    "merchantAppSettings": {
        "public":"{color : \"red\", storeName : \"Cool Mittens Ltd.\"}",
        "id": "1234567890",
        "username": "mittensstore"
    },
    "cart": {
        "currency": "USD",
        "order": {
            "referenceTransactionId":"transaction_55885213",
            "subtotal": 1.15,
            "total": 14,
            "email": "john@example.com",
            "paymentModule": "CUSTOM_PAYMENT_APP-payment-integration",
            "paymentMethod": "Cool payment",
            "tax": 0,
            "ipAddress": "127.0.0.1",
            "couponDiscount": 0,
            "paymentStatus": "INCOMPLETE",
            "fulfillmentStatus": "AWAITING_PROCESSING",
            "refererUrl": "https://mdemo.ecwid.com",
            "volumeDiscount": 4,
            "membershipBasedDiscount": 0,
            "totalAndMembershipBasedDiscount": 0,
            "discount": 1.15,
            "usdTotal": 14,
            "globalReferer": "https://mdemo.ecwid.com",
            "createDate": "2016-04-26 09:14:51 +0000",
            "createTimestamp": 1461662091,
            "items": [{
                "id": 111001,
                "productId": 61003,
                "categoryId": 48003,
                "price": 1.15,
                "productPrice": 1.15,
                "sku": "00007",
                "quantity": 1,
                "shortDescription": "Radish \n The radish (Raphanus sativus) is an edible root vegetable of the Brassicaceae family that was domesticated in ...",
                "tax": 0,
                "shipping": 1,
                "quantityInStock": 0,
                "name": "Radish",
                "isShippingRequired": true,
                "weight": 0.31,
                "trackQuantity": false,
                "fixedShippingRateOnly": false,
                "imageUrl": "https://images.ecwid.com/store/default-store/00007-sq.jpg",
                "smallThumbnailUrl": "https://images.ecwid.com/store/default-store/00007-80-sq.jpg",
                "fixedShippingRate": 0,
                "digital": false,
                "productAvailable": true,
                "couponApplied": false,
                "selectedOptions": [{
                    "name": "Color",
                    "value": "Blue",
                    "valuesArray": ["Blue"],
                    "type": "CHOICE"
                }],
                "discounts": [
                    {
                      "discountInfo": {
                        "value": 1.15,
                        "type": "ABS",
                        "base": "ON_TOTAL",
                        "orderTotal": 14
                      },
                    "total": 1.15
                    }],
            }],
            "billingPerson": {
                "name": "John Doe",
                "companyName": "Some Company",
                "street": "5th Avenue",
                "city": "New York",
                "countryCode": "US",
                "countryName": "United States",
                "postalCode": "10002",
                "stateOrProvinceCode": "NY",
                "stateOrProvinceName": "New York",
                "phone": ""
            },
            "shippingPerson": {
                "name": "John Doe",
                "companyName": "Some Company",
                "street": "5th Avenue",
                "city": "New York",
                "countryCode": "US",
                "countryName": "United States",
                "postalCode": "10002",
                "stateOrProvinceCode": "NY",
                "stateOrProvinceName": "New York",
                "phone": ""
            },
            "shippingOption": {
                "shippingMethodName": "U.S.P.S. First Class",
                "shippingRate": 10,
                "estimatedTransitTime": "2"
            },
            "handlingFee": {
                "value": 0
            },
            "additionalInfo": {
                "google_customer_id": "123123.12312312"
            },
            "paymentParams": {},
            "hidden": false,
            "extraFields": {
                "referred_by": "Referrer is: Facebook Ads",
                "AFF_ID": "fb-123"
            }
        }
    },
    "token": "abcdefghijklmnopqrstuv1234567890"
}

After you decode the payload, you will get a JSON formatted string with the store and order details to allow customer pay for the order. Fields include:

NameTypeDescription
storeIdnumberEcwid store ID
returnurlstringA URL to send customer to after the payment. More details
merchantAppSettingsjsonMerchant settings for your integration set up by your code. More details
cart<CartDetails>Offset from the beginning of the returned items list (for paging)
tokenstringAccess token of the Ecwid store. Use it to update order status after the payment

CartDetails

NameTypeDescription
currencystringCode of the currency currently enabled in the store
subtotalnumberOrder subtotal. Includes the sum of all products’ cost in the order
referenceTransactionIdstringUnique transaction identification. Used to update order status after payment is processed. See Updating order status
totalnumberOrder total cost. Includes shipping, taxes, discounts, etc.
emailstringCustomer email address
paymentMethodstringPayment method name as specified when registering the app
paymentModulestringPayment processor name in Ecwid
taxnumberTax total
ipAddressstringCustomer IP
couponDiscountnumberDiscount applied to order using a coupon
paymentStatusstringPayment status. Supported values:
  • AWAITING_PAYMENT
  • PAID
  • CANCELLED
  • REFUNDED
  • INCOMPLETE
fulfillmentStatusstringFulfilment status. Supported values:
  • AWAITING_PROCESSING
  • PROCESSING
  • SHIPPED
  • DELIVERED
  • WILL_NOT_DELIVER
  • RETURNED
refererUrlstringURL of the page when order was placed (without hash (#) part)
volumeDiscountnumberSum of discounts based on subtotal. Is included into the discount field
membershipBasedDiscountnumberSum of discounts based on customer group. Is included into the discount field
totalAndMembershipBasedDiscountnumberThe sum of discount based on subtotal AND customer group. Is included into the discount field
discountnumberThe sum of all applied discounts except for the coupon discount. To get the total order discount, take the sum of couponDiscount and discount field values
usdTotalnumberOrder total in USD
globalRefererstringURL that the customer came to the store from
createDatedateThe date/time of order placement, e.g 2014-06-06 18:57:19 +0000
createTimestampnumberThe date of order placement in UNIX Timestamp format, e.g 1427268654
itemsArray<OrderItem>Array of customer’s order items
shippingPerson<AddressDetails>Shipping address details of a customer. Can be missing if no products in cart require shipping
billingPerson<AddressDetails>Billing address of the customer. Can be missing if merchant disabled it in Ecwid Control Panel > Settings > General > Cart.
shippingOption<ShippingOptionInfo>Details of the shipping method selected
handlingFee<HandlingFeeInfo>Handling fee details
additionalInfoMap<string,string>Additional order information if any
paymentParamsMap<string,string>Additional payment parameters entered by customer on checkout, e.g. PO number in “Purchase order” payments
hiddenbooleanDetermines if the order is hidden (removed from the list). Applies to unsfinished orders only
extraFields<ExtraFieldsInfo>Additional optional information about order. Total storage of extra fields cannot exceed 8Kb. See Order extra fields

OrderItem

NameTypeDescription
idnumberOrder item ID. Can be used to address the item in the order, e.g. to manage ordered items.
productIdnumberStore product ID
categoryIdnumberID of category this product was added to cart from. If the product was added to cart from API or Search page, categoryID will return -1
pricenumberPrice of ordered item in the cart including product options and variations. Excludes discounts, taxes
productPricenumberProduct price as set by merchant in Ecwid Control Panel including product variation pricing. Excludes product options markups, wholesale discounts etc.
weightnumberProduct weight
skustringProduct SKU. If the chosen options match a variation, this will be a variation SKU.
quantitynumberAmount purchased
shortDescriptionstringProduct description truncated to 120 characters
taxnumberTax amount applied to the item
shippingnumberOrder item shipping cost
quantityInStocknumberThe number of products in stock in the store
namestringProduct name
isShippingRequiredbooleantrue/false: shows whether the item requires shipping
trackQuantitybooleantrue/false: shows whether the store admin set to track the quantity of this product and get low stock notifications
fixedShippingRateOnlybooleantrue/false: shows whether the fixed shipping rate is set for the product
imageUrlstringProduct image URL
fixedShippingRatenumberFixed shipping rate for the product
digitalbooleantrue/false: shows whether the item has downloadable files attached
productAvailablebooleantrue/false: shows whether the product is available in the store
couponAppliedbooleantrue/false: shows whether a discount coupon is applied for this item
selectedOptionsArray<OrderItemOption>Product options values selected by the customer
taxesArray<OrderItemTax>Taxes applied to this order item
filesArray<OrderItemProductFile>Files attached to the order item
couponAmountnumberCoupon discount amount applied to item. Provided if discount applied to order. Is not recalculated if order is updated later manually
discountsArray<OrderItemDiscounts>Discounts applied to order item 'as is’. Provided if discounts are applied to order (not including discount coupons) and are not recalculated if order is updated later manually

OrderItemTax

FieldTypeDescription
namestringTax name
valuenumberTax value in percent
totalnumberTax amount for the item
taxOnDiscountedSubtotalnumberTax on item subtotal (after applying discounts)
taxOnShippingnumberTax on item shipping

OrderItemProductFile

FieldTypeDescription
productFileIdnumberInternal unique file ID
maxDownloadsnumberMax allowed number of file downloads. See E-goods article in Ecwid Help center for the details
remainingDownloadsnumberRemaining number of download attempts
expirestringDate/time of the customer download link expiration
namestringFile name
descriptionstringFile description defined by the store administrator
sizenumberFile size, bytes (64-bit integer)
adminUrlstringLink to the file. Be careful: the link contains the API access token. Make sure you do not display the link as is in your application and not give it to a customer.
customerUrlstringFile download link that is sent to the customer when the order is paid

OrderItemOption

FieldTypeDescription
namestringOption name
typestringOption type. One of:
  • CHOICE (dropdown or radio button)
  • CHOICES (checkboxes)
  • TEXT (text input and text area)
  • DATE (date/time)
  • FILES (upload file option)
valuestringSelected/entered option value(s) as a string. For the CHOICES type, provides a string with all chosen values (comma-separated). You can use this to simply print out all selected values.
valuesArrayArraySelected option values as an array. For the CHOICES type, provides an array with the chosen values so you can iterate through them in your app.
filesArray<OrderItemOptionFile>Attached files (if the option type is FILES)

OrderItemOptionFile

FieldTypeDescription
idnumberFile ID
namestringFile name
sizenumberFile size in bytes
urlstringFile URL

DiscountInfo

FieldTypeDescription
valuenumberDiscount value
typestringDiscount type: ABS or PERCENT
basestringDiscount base, one of ON_TOTAL, ON_MEMBERSHIP, ON_TOTAL_AND_MEMBERSHIP, CUSTOM
orderTotalnumberMinimum order subtotal the discount applies to
descriptionstringDescription of a discount (for discounts with base == CUSTOM)

AddressDetails

NameTypeDescription
streetstringCustomer’s street
citystringCustomer’s city
companyNamestringCustomer’s company name
countryCodestringCustomer’s country code in Ecwid
countryNamestringCustomer’s country name in Ecwid
postalCodestringCustomer’s postal code
stateOrProvinceCodestringCustomer’s state or province code in Ecwid
stateOrProvinceNamestringCustomer’s state or province name in Ecwid
phonestringCustomer’s phone number

ShippingOptionInfo

FieldTypeDescription
shippingCarrierNamestringShipping carrier name, e.g. USPS
shippingMethodNamestringShipping option name
shippingRatenumberRate
estimatedTransitTimestringDelivery time estimation. Possible formats: number “5”, several days estimate “4-9”

HandlingFeeInfo

FieldTypeDescription
namestringHandling fee name set by store admin. E.g. Wrapping
valuenumberHandling fee value
descriptionstringHandling fee description for customer

ExtraFieldsInfo

FieldTypeDescription
YOUR_FIELD_NAMEstringYour custom name saved for the order extra field. The value length cannot exceed 255 characters

Updating order status

Update order status example

PUT /api/v3/4870020/orders/transaction_55885213?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

{
    "paymentStatus": "PAID"
}

cURL request in PHP example

$url = "https://app.ecwid.com/api/v3/4870020/orders/transaction_55885213?token=1234567890qwqeertt";
$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)));
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);

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 request to your application’s payment URL in corresponding fields:

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

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

Returning 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. It’s 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 QUEUED payment status, customer’s cart will be cleared and they will see 'Thank you for your order’ page
  • If the order is in INCOMPLETE payment status, customer will see the cart page of Ecwid storefront with the same items
  • If the order is in CANCELLED payment status, Ecwid will show the 'Payment error’ page