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="XwYHGNpzBfQesQl4JkZclImcnQXkGhClU2c4-O-8WXZR3N7jx4xkmzbOALXi99ZiV4rpIOOQx6ua_8MC14Emwh4gqOrPqbYctZ54xkbUVmkArtt5TcJd9JngD8C2-DEKJ96Egfi-1RJEgXDau3cUWpelUBXecdAd5g01MW_PZEJzwn8c9WawRw8jLC_kKJX68TU-_jET9GVDaP3rjxmssYPyoSWrMxUNKwaEyzZbdVNkHgQZq6dScNqL1JjP2bnKR7PlK0FhkvNNlC7G0PjnAfSAvw41zdIu2UjYutiba2gwQf5iYH-4J6J8sM4iRmTlFMEJwAFClffXRjacntxnV3PsLNvbOp8VFC2hzU2fsOQBSM8YmhsDgTRDdjQK1u7j2kiUuJbTEAijsQjoxicDlQJJ_tYh-6pfsyop9plL9ifhOylrUUe4VOsAVNi7iQ1UCVfuutsbm8aMYMQY4NmFKVK2K6Q_tguI5-NN9r9aG16MB3lFAPPI9SJgw0W9ucBSF8mWKQ6DVV9w7iFnq5Clw4TGCYw3QA_pb02TeCDZS8P-cFau21BPUas-K_JuebUD3BhGct8gHqpP_nqwwBj97bN94muerSxveT4m_jifR_bsbRZgDxtoDP8jiOK9O7ACWXsZhuTUhMxXYaQ8F3e0AIHp2FgQmL6pc0lTMZaiyqPr14WdYyqKHeG0Z8OrRVN3_zvfysb-SahJs18DElm8pBFqOrAiopEfFoAEll5cX5ZC09w9wy6SkheZOvv0l2KoH_lS6ovPgw6AArZw8lvNEQPOoDy4VQIofSOUYezCYwYDqQ1Im0yR3tLKvuONFPNUdQ5qkWCvyRhZyGqIs2VIiRJV6ErWmOYS_06Ri12Q3236Q3W2bKuEAMca6d9_PL51Q_GtBuxk5bWTTvTqDA3uL2Cy7WdE-VPesRmgmngozlbjjWQfXrS8slhFZpQvy0Pjqp0c7iNKhG7dkTLlpqFFGLCGpQ6l8yMhzluG0ZTOTy7iuNxcSWfBUhy1ZnOS-M8LzLY5UZYxvsK5PHyEdQjOxqxUfO0ORkNEFmhM33f4XLB6EuPyT2x4yt8F3DmctsHXdfuWYyzEHHe86IjqWOuFAzLMo0EhDVSAxtVvWt3FQlWBw-vRGAgG2XtXcNSbb00wj2T3uISHOlhnjPKs1nYMrXTKSxQ5X98YHpmp-09eOu_zkidYquhoJo3ioldzMYBI08wI9WFUzEc7ALr0YPr3XoVRqKvolVNExcPgCHEe4BcIcgsoPzLm5UolBST6_fB4sGJGxiKAfgAUb9Bv_PT7GYSbIfcfn17UPaO_1nXuQcXAB3b1jGbZoCaJbXhBJVGc1vZAzdAq69eyIuiQygWSuSLCK9DEffqtqfBq_YwDcQIbSv9ZTcVyRXYQYGNCyAdER5wE9B2dv0qe7wxSFElt3t6cGPSBZnA8-pcNzsUhBChaYJuPj2JJRGSkvdAjnl3NREbxogqayPGbqVf_lYKp9Q192seMKw99dswCB9EIDThdOwFu_sXeo57RolqFqOknzYI0QedcBb6sEv_g_OwMNZZW3oxCEIB76k-6zgUBiAQhK0s95NzlFrJ9cCO3Kvk-6NS-du_Ow3uSiRmCSbgA5djAnjx--XbJZpCo4vQzOwsV0CHjtato3KiZjyTRw5d4aJZt4Vp-fAwOS9PvXAordsVPL7Ns0IiaKb81EF0bwCDLZRE-oR4nndiiyVhK-JlRbSERm32VPPu7271PaXGvxO8sSGyTLhX1ABHKeteboX1TzXM-TPq7-uXeDQw5bJe6lLMn6438NhxsxHa7bygktYvSs6hoZY7qq6oPTs5u_N_8qVKW7T2UpHpFKyjVCPYpThIGG1Onx3B6jZ74QAnHhYT5DVgg4j2pJoy3pGWLZ6hn8BRto0-eUT4fUT2e5-37SVfRvCY56jm69nEKbbq3e98I6wa6PvIGUILbGjN0LpuT4h0Q2b4pJDyNqPV8sb4dLjXYwRwotpc6lhxEHQylIxIWsfso4DSZ4xGVA8u9sLaNSNO3yMgME1jZ7z5GGo7m4jXIMLW-LYmB9razHuavXZl8KmUsNF8PcM6LwK0sHUyPcTwgwWqOaADPP08PXFMcMtlywg28Kt56gpJaeH_FLloEU3DYPEEfawEzoqxbu18tCr3Gwc6LqkxsyNCJvuQ63DWee5Ff5FB-NDrGm9T4sd69y0OttyY1I96GTIHj-aPxDfd9r_ZJdcBQOpYao_DZtS8aT4p_hPedaj978cvYGJSjpZZFctsx5SyYOGWL48Jce2rAKswRy0fkx15PUIgH3Yp5Kf7lEl--lr3IpNI8FbmPCC0KyfqymffFT1vtUG64B4CQxeYavOoszOHgAAbqKBXKSmwfYfalAnXaFQWmMyAiGJHx7-7xzxJ6IXvBkwaKXsaeBnFZ1sC0rp4MM3FT48q6o9hIrUV731Wg_t_EkH6aS71jD8xxxHwq3AbNEWIcUfPve8b55Re0_ttOky6VV7yOGQyTATk4gCchy_2HAH4P9O_rrVL2ir9rwX8Jk2xD5In5lWt-KYaY2Uyanhs7ac5X2SOdJJXqlg0fbhiHJAbsCkG_jwOC38K-JL0p6RRoKsV44GO0Qcqh6vzDWVhDPdYq4JAK_odBlDOdfHWfbATPftrmEahKeyNctlBP7g_oYtBmkUn-2uSVv670L3GPzLS8daxEERKv9DF1BoIXI3Ms4EXrUV5HwNafceMt-hS05AEpUl13srE_fL0xMJGmI3tgg-t6S-H_NMYqs85sgjclTrZkluHRY_2qGD8KgxTm-CV5IZ7gihuH68sjYXS-sCGTrHCTGVG1KkBrbkmAjut3ZTIgIoL-6p-begqeq9SLSQ0MDcBXIDa-DPtHnctAEv-vQmvOOq76YRcAC5FYwQZT5rj6ns0bqTWC24zLtQqxQFC9an802zVuIczLJoSD"/>
</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": {
            "vendorOrderNumber": "AS64-0001",
            "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",
            "orderNumber": 64,
            "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"
                }]
            }],
            "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
        }
    },
    "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
currencyUSDCode of the currency currently enabled in the store
vendorOrderNumberstringOrder number with prefix and suffix defined by admin, e.g. ABC34-q
subtotalnumberOrder subtotal. Includes the sum of all products’ cost in the order
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
orderNumbernumberUnique order number without prefixes/suffixes, e.g. 34
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
billingPerson<AddressDetails>Billing address of the customer
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.

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 the category this product belongs to. If the product belongs to many categories, categoryID will return the ID of the default product category. If the product doesn’t belong to any category, 0 is returned
pricenumberPrice of ordered item in the cart
productPricenumberBasic product price without options markups, wholesale discounts etc.
weightnumberProduct weight
skustringProduct SKU. If the chosen options match a combination, this will be a combination 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

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

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

Updating order status

Update order status example

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

{
    "paymentStatus": "PAID"
}

For Ecwid to find out the result of the payment, your application must update the order status before returning them back to the storefront. Updating order status can be performed using a call to Ecwid’s REST API and its Orders endpoint.

In order to update an order, you will need these details: order number, store ID and an access token. All of these details are provided in a request to your application’s payment URL in a corresponding fields: orderNumber field in the cart object, storeId and token fields in the request.

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

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
  • If the order is in CANCELLED payment status, Ecwid will show the 'Payment error’ page.