In-Store API

Give your shoppers the option to pay with Zip in-store with our point-of-sale API.

The first API call you will make in processing a zip in-store payment is a call to our /purchaserequests endpoint. This request is made once a customer provides their Zip pin / barcode for the transaction.

This API call will contain:

• Order information
• The customer in-store pin / barcode
• Store location information

The Zip API response will contain:

• An order reference - to identify the newly created order
• An order status - This will return as 'pending'

This /purchaserequests API call should be made from your server and not directly from the client front end.

Amount and order reference

The total amount to be paid via Zip should be passed in your request as the 'payAmount'. This value will be deducted from the customers available funds.

Your transaction reference for the payment should be passed as 'refCode' . This should be the reference that you would like to appear on your Zip Disbursement Report.

An example of passing these is below:

{
    "payAmount": 280,
    "refCode": "your_transaction_reference"
}

Order information

Zip require certain customer order details to be passed at the time of purchase as below:

• Total amount in AUD
• Order Items

Here is an example of how this information can be passed:

 "order": {
    "totalAmount": "280"
}

Items

When a customer order is created, the item details should be passed in the purchase request to Zip. Below is an example of how this could look:

"items": [
    {
        "name": "Awesome shoes",
        "amount": 200,
        "quantity": 1,
        "type": "sku",
        "reference": "001"
    },
    {
        "name": "Awesome pants",
        "amount": 100,
        "quantity": 1,
        "type": "sku",
        "reference": "002"
    }
]

Discounts

The majority of POS systems support some form of discount code or promotion feature. In these scenarios, in order for the checkout sums to add up as expected, Zip require these discount amounts to be passed to us in the /purchaserequests API call.

The way this should be handled, is by simply adding an additional 'item' to the request of 'type: discount' e.g.

"items": [
      {
        "name": "Loyalty Discount",
        "amount": -20,
        "quantity": 1,
        "type": "discount"
      }
]

Customer 6-digit pin / barcode

This is the key to identifying the customer account and verifying the available funds for the order.

"accountIdentifier": {
    "method": "token",
    "value": "XXXXXX"
}

Store location information

Each order must identify:

• The transacting store
• The staff reference
• The device reference

The store 'Location ID' is a value provided by the Zip team for each store location.

The staff and device references are your own references for each and need not be communicated to Zip. These will simply be used to assist in troubleshooting any issues in the order logs:

This can be passed as below:

"originator": {
     "staffActor": {
          "refCode": "your_staff_member_reference",
          "name": "your_staff_member_name"
      },
      "locationId": "XXXXX",
      "deviceRefCode": "your_device_reference"
}

Platform Identifier

📘

Platfrom Intgerations Only

This is an identifier that must be sent for platform integrations that will have many Zip partners using the one integration.

As a part of all in-store channel partner certifications, Zip require a piece of metadata to be sent in all requests that identifies the 'Platform' that is processing a transaction.

This is simply passed in all POST /purchaserequests requests inside the payload within the 'metadata' object.

Below is an isolated example:

"metadata": {
    "partner": "Example Channel Partner"
}

The full request

An example payload can be found below:

{
    "payAmount": 280,
    "refCode": "your_transaction_reference",
    "order": {
        "totalAmount": 280,
        "items": [
            {
                "name": "Awesome shoes",
                "amount": 200,
                "quantity": 1,
                "type": "sku",
                "reference": "001"
            },
            {
                "name": "Awesome pants",
                "amount": 100,
                "quantity": 1,
                "type": "sku",
                "reference": "002"
            },
            {
                "name": "Loyalty Discount",
                "amount": -20,
                "quantity": 1,
                "type": "discount"
            }
        ]
    },
    "accountIdentifier": {
        "method": "token",
        "value": "XXXXXX"
    },
    "originator": {
        "staffActor": {
            "refCode": "your_staff_member_reference",
            "name": "your_staff_member_name"
        },
        "locationId": "XXXXX",
        "deviceRefCode": "your_device_reference"
    },
    "metadata": {
        "partner": "Example POS provider"
    }
}

📘

Polling the order status

Once the order has been triggered, the order status must the begin to be repeatedly checked until the order status is 'approved'. This is detailed in Polling the order status