Transaction Basics

A High Level Understanding

Below are some high level concepts involved in a Zip Instore API transaction

Though there is more detail provided in the coming section, it is key to understand the below before proceeding:

All Zip transactions require at least 2 API calls. A call to our /pos/order endpoint to initiate the customer checkout, then a call to our /pos/order/{id} endpoint to retrieve the order status
For orders that have been created with a paymentType of auth, then a call to our /pos/order/{id}/commit endpoint must be made to 'capture' the funds
Only if a customers checkout is approved, should the /pos/order/{id}/commit call be made, otherwise, alternative messaging and handling will come into play

Payment Flow

Once a customer's checkout has been approved, Zip API integrations will utilise either the 'Payment' or 'Auth' methods when completing Zip transactions

Payment

A single API call to the /pos/order endpoint is required to finalise a transaction

Once this request is made, the /v2.0/pos/order/{id}/status endpoint should be called to verify the order has been Approved and the funds for that transaction will be disbursed to the partner the following business day

Authorise and Capture

First, an API call is made to the /pos/order endpoint whereby the customer has an authorisation taken from their card at the time of approval, followed by a second call to /pos/order/{id}/commit to 'Capture' and commit the transaction

An authorisation will hold the funds from the customer's card, until the goods are ready to be fulfilled, at which point the transaction can be manually captured

The funds for that transaction will NOT be disbursed to the partner until they have completed the /pos/order/{id}/commit call for that transaction

##Suggested Method

The proposed Payment Method for a standard instore API integration is the Payment method

Key Order Information

For all transactions, there are some key pieces of information that will need to be passed to Zip. Over time, we have isolated some of these items that are often overlooked. These are highlighted below to ensure they are all taken into account when passing data to the Zip API

Item Details

When the customer makes a Zip purchase, it is important that some details are conveyed to Zip in the /pos/order API call as this information will be exposed to the customer in the Zip app/portal

The way this should be handled, is by simply passing through name: string, quantity: integer, price: number when calling our API. For example:

"items": [
    {
      "name": "Item 1",
      "quantity": 1,
      "price": 50
    },
    {
      "name": "Item 2",
      "quantity": 1,
      "price": 50
    }
  ]

There are other details such as description and SKU but these are not exposed to customers and are for manual reporting purposes only