Web checkout API

Create a charge

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

The API call you will make to complete a zip payment is a call to our /charges endpoint. This request is made once you have received an Approved checkout result back from Zip.

📘

Note

The /charges API call to complete the payment authorisation must be made within 15 minutes once a checkout has been approved. Checkouts will expire if not completed within this timeframe.

This API call will contain:

• Authority
• Reference
• Amount
• Currency
• Capture flag
• Customer details
• Order information

The Zip API response will contain:

• Charge Id - a unique reference for your charge, to be used for refunds or cancel / capture flows
• State - the current state of the charge (authorised captured approved)
• Captured amount
• Refunded amount
• Product
• Receipt number - a unique customer facing reference for your charge. To be printed on receipts and is used in legacy 'in-store' refund scenario's.

📘

State validation

If you are validating the value of the state in the response please ensure your system accepts the values listed above as successful responses.

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

Authority

Zip require an authority token to process a charge. This will be:

• The checkout Id obtained from the first API call to Zip

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

"authority": {
    "type": "checkout_id",
    "value": "au-co_xxxxxxxxxxxxxxxxxxx"
}

Charge details

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

• Reference
• Amount
• Currency
• Capture flag

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

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

Capture flag

When a charge is made, it must be specified if the funds should be immediately captured or only authorised (see API calls and Payment Flows). This can be passed to Zip as below:

{ 
    "capture": true
}

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"
        }
    }
}

The full request

An example payload can be found below:

{
  "authority": {
    "type": "checkout_id",
    "value": "au-co_xxxxxxxxxxxxxxxxx"
  },
  "reference": "your_order_reference",
  "amount": 300,
  "currency": "AUD",
  "capture": true
}

With a successful response from Zip, you have now completed your charge!

📘

Order Management

• If you have completed your charge with the capture flag set to false, you will still need to capture or cancel the charge.
• Additionally, implementing refunds is advised, but not required

📘

Go live

Next its time to review your go live requirements