Transaction Basics
Transaction Basics
A High Level Understanding
Below are some high-level concepts involved in a Zip Online API transaction
Though there is more detail provided in the coming section, it is key to understand the below before proceeding:
-
All Zip transactions require at least 2 API calls. A call to our
/order
endpoint to initiate the customer checkout, then a call to our /order/{id} endpoint to retrieve the order status -
For orders that have been created with a paymentType of auth, then a call to our
/order/{id}/capture
endpoint must be made to 'capture' the funds -
Before the
/order/{id}/capture
API call can be made, the customer must complete their Zip checkout flow (by following the redirectUrl returned from the/order
endpoint call) -
Only if a customer's checkout is authorised, should the
order/{id}/capturecall
be made, otherwise, alternative messaging and handling will come into play
Payment Type
Once a customer's checkout has been approved, Zip API integrations will utilise either the 'Payment' or 'Authorise and Capture' methods when completing Zip transactions
Payment
A single API call to the /order
endpoint is required to finalise a transaction
Once this request is made, the GET /order/{id}
endpoint should be called to verify the order has been Approved
and the funds for that transaction will be disbursed to the partner the following business day
Authorise and Capture
First, an API call is made to the POST /order
endpoint to create the redirectUrl
for the customer to go through checkout. Once the customer completes the order, this will convert the order state to Authorised. This should then be followed by a second call to the /order/{id}/capture
endpoint to Capture
the funds.
An Authorisation will hold the funds from the customer's card, until the order is ready to be fulfilled, at which point the transaction can be captured
Uncaptured orders in the Authorised
state will expire after 15 minutes if left not captured/acknowledged
and the Authorisation held on the customer's card will be voided/reversed.
If there needs to be a delay before capturing the amount, the /order/acknowledge
call should be made to prevent the order from expiring after 15 mins - but will then expire after 7 days if left uncaptured.
The funds for that transaction will NOT be disbursed to the partner until they have completed the /order/{id}/capture
for that transaction
This method is most commonly used for partners who backorder stock, or do not have the stock on hand at the time of purchase
Suggested Method
The proposed Payment Method for a standard online API integration is the Payment
method
Key Order Information
For all transactions, there are some key pieces of information that will need to be passed to Zip. Over time, we have isolated some of these items that are often overlooked. These are highlighted below to ensure they are all taken into account when passing data to the Zip API
Item Details
When the customer makes a Zip purchase, it is important that some details are conveyed to Zip in the POST /order
API call as this information will be exposed to the customer in the Zip app/portal
The way this should be handled, is by simply passing through name: string
, quantity
: integer
, price: number
when calling our API. For example:
"items": [
{
"name": "Item 1",
"quantity": 1,
"price": 50
},
{
"name": "Item 2",
"quantity": 1,
"price": 50
}
]
There are other details such as description
and sku
but these are not exposed to customers and are for manual reporting purposes only
Pickup vs Delivery
When a customer checkout online, but chooses to pickup the goods/click & collect rather than have the goods delivered, it is important that this information is conveyed to Zip in the POST /order
API call
The way this should be handled, is by simply passing pickup: true
when calling our API. For example:
shipping": {
"pickup": true
}
Updated 11 months ago