Home
Guides

Create a Checkout

Suggest Edits
Plugin icon

Web checkout API

Create a checkout

Give your shoppers the option to pay with Zip on your web platform with our web checkout solution.

The first API call you will make in processing a zip payment is a call to our /checkouts endpoint. This request is made once a customer chooses Zip as their payment method for a transaction.

This API call will contain:

  • Customer details
  • Order information
  • Configuration information

The Zip API response will contain:

  • A checkout Id - to identify the newly created checkout
  • A redirect url - to redirect the customer to the zip checkout flow where they will complete their application or log in to their zip account to confirm the payment.

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

Customer details

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

  • First and Last name
  • Email address
  • Mobile phone number
  • Billing Address

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

"shopper": {
    "title": "Mr",
    "first_name": "Test",
    "last_name": "Tester",
    "email": "[email protected]",
    "phone": "0400000000",
    "billing_address": {
        "first_name": "Test",
        "last_name": "Tester",
        "line1": "10 Spring St",
        "city": "Sydney",
        "state": "NSW",
        "postal_code": "2000",
        "country": "AU"
    }
}

Order information

Zip also require details of the order to be passed in the checkouts request, including:

  • Reference
  • Amount
  • Currency
  • Items

Here are some examples of how this information can be passed:

"order": {
    "reference": "your_order_ reference",
    "amount": 300,
    "currency": "AUD"
}

Items

When a customer fills their cart, these details should be passed in the checkouts request to Zip. Below is an example of how this could look:

"items": [
    {
        "name": "Awesome shoes",
        "amount": 200,
        "quantity": 1,
        "type": "sku",
        "reference": "001",
        "image_uri": "https://yourimage.com/shoes_image_url",
        "item_uri": "https://youritem.com/shoes_item_url"
    },
    {
        "name": "Awesome pants",
        "amount": 100,
        "quantity": 1,
        "type": "sku",
        "reference": "002",
        "image_uri": "https://yourimage.com/pants_image_url",
        "item_uri": "https://youritem.com/pants_item_url"
    }
]

Discounts

The majority of ecommerce websites 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 /checkouts API call.

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

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

Pickup vs Delivery

When a customer checks out online, but chooses to pickup the goods in-store rather than have them delivered, it is important that this information is conveyed to Zip in the /checkouts API call.

The primary reason for this is our fraud risk and decisioning engine, which will flag applications as suspicious if the same store address is repeatedly used.

The way this should be handled, is by simply passing 'pickup: true' when calling our API e.g.

"order": {
    "shipping": {
      "pickup": true
    }
}

Alternatively, for a standard online delivery the shipping address should be passed:

"order": {
    "shipping": {
        "pickup": false,
        "address": {
            "first_name": "Test",
            "last_name": "Tester",
            "line1": "10 Spring St",
            "city": "Sydney",
            "state": "NSW",
            "postal_code": "2000",
            "country": "AU"
        }
    }
}

Configuration Information

This is the final part of the checkouts request payload that will give Zip the correct address to return the customer, AFTER they have logged into or signed up to their Zip account.

The 'redirect_uri' is simply your desired url, where Zip will redirect the customer, appending the result and checkout Id

"config": {
    "redirect_uri": "https://yourserver.com.au/zip_order_complete"
}

Here is an example of how Zip would return a successful order confirmation:

https://yourserver.com.au/zip_order_complete?result=Approved&checkoutId=co_xxxxxxxxxxxxxxxx

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 online 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 /checkouts requests inside the payload within the 'metadata' object.

Below is an isolated example:

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

Tokenisation flag

Tokenisation is a powerful feature that allows a Zip partner to retain a 'Token' that can be used to perform:

  • Automated subscription charges
  • Streamlined web checkout charges

There are several flows associated with this functionality that allow the customer to approve the features use for a given period of time.

The most common scenario for the use of this feature is for subscription services that charge customers on a scheduled basis.

📘

Available in Australia Only

This is not a feature that is currently globally available.


📘

Adding Zip from payment settings

Zip support a $0 checkout amount in the /checkouts request payload to trigger a 'linking only' login flow for customers. This should be used when customers are adding Zip from payment settings on as part of your onboarding flow, when no immediate payment amount is involved in the customer experience.


A token links a specific Zip customer account to your merchant account, meaning this token can be stored against the customer record and used in place of a checkout_id to make /charges API calls.

This allows /charges to be placed against that customer account with no further interaction from the customer themselves.

To create the initial token you will first have had to make your /checkouts API call, being sure to include the below tokenisation feature flag (without this the checkout_id will no work to create a token):

"features": {
    "tokenisation": {
        "required": true
    }
}

The full request

An example payload can be found below:

{
    "shopper": {
        "title": "Mr",
        "first_name": "Test",
        "last_name": "Tester",
        "email": "[email protected]",
        "phone": "0400000000",
        "billing_address": {
            "first_name": "Test",
            "last_name": "Tester",
            "line1": "10 Spring St",
            "city": "Sydney",
            "state": "NSW",
            "postal_code": "2000",
            "country": "AU"
        }
    },
    "order": {
        "reference": "your_order_reference",
        "amount": 280,
        "currency": "AUD",
        "items": [
            {
                "name": "Awesome shoes",
                "amount": 200,
                "quantity": 1,
                "type": "sku",
                "reference": "001",
                "image_uri": "https://yourimage.com/shoes_image_url",
                "item_uri": "https://youritem.com/shoes_item_url"
            },
            {
                "name": "Awesome pants",
                "amount": 100,
                "quantity": 1,
                "type": "sku",
                "reference": "002",
                "image_uri": "https://yourimage.com/pants_image_url",
                "item_uri": "https://youritem.com/pants_item_url"
            },
            {
                "name": "Loyalty Discount",
                "amount": -20,
                "quantity": 1,
                "type": "discount"
            }
        ],
        "shipping": {
            "pickup": true
        }
    },
	"features": {
    	"tokenisation": {
        	"required": true
    	}
    }, 
    "config": {
        "redirect_uri": "https://yourserver.com.au/zip_order_complete"
    },
    "metadata": {
      "platform": "Example Channel Partner"
    }
}

After you have created a Checkout

Once you have received a successful /checkouts API response, you will need to:

  • Store the 'id' returned by the API against your order / cart records
  • Redirect the customer to the url returned by the API

Once redirected, the customer will see the Zip login screen and either sign in or sign up to their Zip account.

After the customer has completed this step, they will be redirected back to your website. Specifically to your 'redirect_uri' that was passed to Zip in your /checkouts request.

There will be two key values appended to this url that should be consumed by your code and handled appropriately.

https://yourserver.com.au/zip_order_complete?result=Approved&checkoutId=co_xxxxxxxxxxxxxxxx

Result

This is the status of the customer application / order confirmation. This will be one of three possible options:

  • Approved - Proceed to create a charge for this order
  • Declined - Redirect the customer to the payments page to choose an alternative payment option
  • Referred - Redirect the customer to the payments page to choose an alternative payment option

📘

Your order is NOT complete

This result, even if Approved, does not indicate the payment process is complete. This is simply confirmation from Zip that the customer account has the available funds for the order and that both Zip and the customer have approved this checkout ID to be used to create a charge

Checkout id

This is the same value that was stored against your order / cart records after receiving a successful /checkouts API response.

This value should be used to identify the cart associated with the result.



📘

Complete your charge

Once the customer has logged in and Approved the order, you will receive their approval via redirect from Zip and you can then Create the Charge

Updated over 1 year ago