Poq-Documentation

Web Checkout Integration Part 1: Cart Transfer Integration

Overview

If your app has a Native Account Integration (with native user registration and sign-in functions) purchases can happen for both logged in and guest users.

For authenticated users, in most cases, cart transfer won’t be needed as the bag will be maintained in your system (via an API integration). The user will always see the same information in the app and on the website.

For guest users, however, the bag is kept in the app and cart transfer is required.

High Level Diagram

The below diagram illustrates the main flows and highlights the key additional step that Option 1 requires when compared to the other available options (2A and 2B). You can refer to the diagram as you learn more about each option in the following sections.

High Level Diagram for Cart Transfer

OPTION 1: API Endpoint Integration

API Endpoint Integration is the most powerful and flexible option as it gives you complete control over the requests to your website.

We need two endpoints to transfer the cart:

An API endpoint that returns the required information to construct a request that will open the check out page of your website with the items added on the app.
A web page that opens when the request with the provided details is made.

To ensure that shoppers get exactly the same items as the app bag, the website checkout page should only contain items that are provided via the API request.

The Flow

We make an HTTP request to your back-end with the cart items information.
Your back-end returns an HTTP response with an HTTP request description as its body.
The app uses this information to construct an HTTP Web Request.
The app opens a web view and makes the constructed request to your back-end.
Your back-end response with the bag or check-out page of your website.

Creating The API Endpoint

We need an API endpoint implementation on your end to create a request that opens the checkout page of your website in a web view.

Request From Poq

We need your endpoint to accept and return the following request and response. The endpoint URL is configurable.

Request body fields:

Name	Description
items	Array. Each element represents an item in the bag.
items[].quantity	The amount of units to purchase for that item.
items[].sku	The unique SKU of that item.
currency	The currency code to use for the transaction.
reference	A string uniquely generated for each order. Maximum 32 characters. This reference is used to match orders in our system to yours in case a discrepancy happens.

Request to your backend:

POST {Endpoint URL} 

Content-Type: application/json

{
  "items": [{
    "quantity": 1,
    "sku": "item_1_sku"
  }, {
    "quantity": 5,
    "sku": "item_2_sku"
  }],
  "currency": "GBP",
  "reference": "[Poq Order Reference: UUID]"
}

Response From Your Backend

The response body is assumed to be of JSON format.

Response body fields:

JSON Field Path	Required	Description
url	Yes
httpMethod	No	One of the following: `GET`, `POST`. Assumed to be `GET` when not present.
body	No	HTTP request body for the cart transfer request to render the checkout page.
cookies	No	Array. Cookies to attach to the cart transfer request to render the checkout page.
cookies[].name	Yes	Only required when there are cookies to send.
cookies[].value	Yes	Only required when there are cookies to send.
cookies[].expireDate	No	ISO 8601 Date.
cookies[].isHttpOnly	No
cookies[].isSecure
cookies[].path
headers	No	HTTP Headers to attach to the cart transfer request to render the checkout page.
headers[].name
headers[].value

Example:

{
  "url": "https://yourstore.com/checkout",
  "httpMethod": "POST",
  "cookies": [
    {
  	  "name": "auth",
  	  "value": "qwer1234",
  	  "expireDate": "2028-09-15T15:53:00+05:00",
  	  "isHttpOnly": true,
  	  "isSecure": true,
  	  "path": "/"
  	}
  ],
  "headers": [
    {
  	  "name": "Custom-Header",
  	  "value": "custom value"
  	}
  ]
}

We recommend implementing a POST request as GET requests may exceed maximum URL length when there are a large number of items in the user bag.

⚠️ Note: The Content-Type HTTP header of the POST requests that the apps make is always set as application/x-www-form-urlencoded. If the API Response includes a different content type header, it is ignored. This is due to in-app browser behaviour.

App uses this information to generate a request to render the checkout page of your website in a web view.

## OPTION 2: Web Request Generation

With this option, we generate a web checkout URL on our end and make a request to your website. We expect your website to respond with the checkout page to show in a webview in the app. Please see Web Page Setup for specifications on how to set up the web page.

OPTION 2A: HTTP Post Request

Request From Poq

We need your website to accept the following request and respond with the web page. The base endpoint URL is configurable.

⚠️ Note: The Content-Type HTTP header of the POST requests that the apps make is always set as application/x-www-form-urlencoded. This is due to in-app browser behaviour.

Request URL Body Fields:

Name	Description
`items`	An array of items in the user cart.
`item[].sku`	The sku of the item.
`item[].price`	The sales price of the item.
`item[].quantity`	The amount of units to purchase for that item.
`currency`	The currency code to use for the transaction.
`reference`	A string uniquely generated for each order. Maximum 32 characters.

Request to your backend:

POST {Base URL} HTTP/1.1
Content-Type: application/x-www-form-urlencoded
 {
  "items": [
    {
      "sku": {sku},
      "quantity": {quantity},
      "price": {price}
    }
  ],
  "currency": {currency},
  "reference": {reference}
}

For example:

POST https://myshop.com/checkout 
Content-Type: application/x-www-form-urlencoded
 {
  "items": [
    {
      "sku": "sku1",
      "quantity": 2,
      "price": 9.95
    }, {
      "sku": "sku2",
      "quantity": 1,
      "price": 14.95
    },
  ]
  "currency": "GBP",
  "reference": "f321aad2-0760-48e5-b1cd-894293cb9fc6"
}

OPTION 2B: HTTP Get Request

IMPORTANT Since maximum HTTP request length is 2048 transferring carts with many items may fail with this method. We strongly advise using one of the methods described above instead.

We need your website to accept and return the following request and respond with the web page. The base endpoint URL is configurable.

Request query string fields:

Name	Description
`{index}`	A zero based index variable.
`item_{index}_sku`	The sku of the item at the index {index}.
`item_{index}_quantity`	The amount of units to purchase for that item.
`currency`	The currency code to use for the transaction.
`reference`	A string uniquely generated for each order. Maximum 32 characters.

Example request to your backend:

GET https://myshop.com/checkout?item_0_sku=samplesku1&item_0_quantity=1&item_1_sku=samplesku2&item_1_quantity=5&currency=GBP&reference=f321aad2-0760-48e5-b1cd-894293cb9fc6 HTTP/1.1