API calls and Payment Flows

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

When completing a payment using the Zip API, there is a common customer experience , requiring the customer to sign in or sign up and approve the order. While this experience remains the same across the various integration types, there are a number underlying options available that can be leveraged to benefit your specific business requirements.

The Zip API supports either the 'Immediate Capture' or 'Authorise and Capture' flow when completing transactions. Your choice here will determine:

• The API calls that need to be made to Zip to complete a transaction
• When you will receive the funds from Zip
• When your customers will need to begin repayment on their purchase

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.

Immediate Capture Flow

There are a number of benefits to using the immediate capture flow, which is the most common integration type with Zip. Using this flow:

• A single API call to the /charges endpoint is required to finalise a transaction
• The funds for the transaction will be disbursed to you the following business day
• Your customer will be able to begin repayments on their purchase from that date

The distinguishing detail to trigger immediate capture is to include the flag 'capture: true' in your /charges API request.

Authorise and Capture Flow

There are certain business types or payment flows that can benefit from the delayed payment capture offered by the auth and capture flow. Using this flow:

• An additional API call to the /capture endpoint is required to finalise a transaction
• The first /charges call to authorise the transaction amount and the second /capture call to capture the funds (it is possible to manually capture via the Zip Dashboard instead)
• Customer funds are guaranteed once authorised and locked from being spent elsewhere
• The funds for the transaction will NOT be disbursed until the second API call (the 'Capture' request) is made to Zip. Once this is made, you will receive the funds the following business day
• Your customer is not required to begin repayments on their purchase until the second API call (the 'Capture' request) is made to Zip

The distinguishing detail to trigger delayed capture is to include the flag 'capture: false' in your initial /charges request.

Why use Auth and Capture?

• Fast moving or limited stock: If stock of an item can quickly become unavailable while a customer completes payment or needs to be sourced from a supplier
• Service or experience purchases: If a customer has purchased a service or experience that is not scheduled for an extended period of time (greater than 14 days)

Tokenised flow

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
• Adding ZIp as a stored payment type via your payment settings

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.

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 (required to create a token).

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

The /tokens API call will contain:

• Authority Type
• Value

The Zip API response will contain:

• Token Id - a unique reference for your token
• Token value - the actual token to be used for processing /charges
• Token active status - true or false
• Created date

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

The below shows the full token creation flow (including checkout approval and initial charges):

The below shows the flow for subsequent charges using the token, whcih can also be used of ofline charging and recurring payments from the backend:

📘

Begin transacting

Having chosen your payment flow, we can now begin making the API calls outlined above, starting with creating a checkout