Transaction Basics

A High Level Understanding

Below are some high-level concepts involved in a Zip Online 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 /order endpoint to initiate the customer checkout, then a call to our /order/{id} endpoint to retrieve the order status
For orders that have been created with a paymentType of auth, then a call to our /order/{id}/capture endpoint must be made to 'capture' the funds
Before the /order/{id}/capture API call can be made, the customer must complete their Zip checkout flow (by following the redirectUrl returned from the /order endpoint call)
Only if a customer's checkout is authorised, should the order/{id}/capturecall be made, otherwise, alternative messaging and handling will come into play

Payment Type

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

Payment

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

Once this request is made, the GET /order/{id} 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 POST /order endpoint to create the redirectUrl for the customer to go through checkout. Once the customer completes the order, this will convert the order state to Authorised. This should then be followed by a second call to the /order/{id}/capture endpoint to Capture the funds.

An Authorisation will hold the funds from the customer's card, until the order is ready to be fulfilled, at which point the transaction can be captured

Uncaptured orders in the Authorised state will expire after 15 minutes if left not captured/acknowledged and the Authorisation held on the customer's card will be voided/reversed.

If there needs to be a delay before capturing the amount, the /order/acknowledge call should be made to prevent the order from expiring after 15 mins - but will then expire after 7 days if left uncaptured.

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

This method is most commonly used for partners who backorder stock, or do not have the stock on hand at the time of purchase

Suggested Method

The proposed Payment Method for a standard online 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 POST /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

Pickup vs Delivery

When a customer checkout online, but chooses to pickup the goods/click & collect rather than have the goods delivered, it is important that this information is conveyed to Zip in the POST /order API call

The way this should be handled, is by simply passing pickup: true when calling our API. For example:

shipping": {
    "pickup": true
  }