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.
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 yourAPI request.
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 /capture call to capture the funds (it is possible to manually capture via the Zip Dashboard instead) call to authorise the transaction amount and the second
- 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 initialrequest.
- 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)
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
/checkoutsrequest 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](/reference/create-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 (required to create a token).
The /tokens API call will contain:
- Authority Type
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
ThisAPI 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:
Having chosen your payment flow, we can now begin making the API calls outlined above, starting with creating a checkout
Updated about 1 year ago