/purchaserequests
A purchase request signifies a new transaction via zip. Based on the URL used this could be a pending transaction that requires confirmation from a customer, or an immediately approved/declined transaction. Calling this endpoint will create a new purchase request and return the state of this newly created purchaseRequest to the caller.
Authorise and Capture FlowA purchase request can be specified as 'Authorise Only', meaning that the funds are locked against the customer account, but not charged until the merchant captures the payment manually via the Zip Dashboard.
To Authorise only upon the initial transaction, you will need to include the 'Capture' field in the purchase request, specifying capture
as false.
capture:false
– capture
will be true by default if not specified.
{
"originator": {
"locationId": "3696",
"deviceRefCode": "205203",
"staffActor": {
"refCode": "3071"
}
},
"refCode": "6ifb67bf76faaa",
"payAmount": 4.99,
"capture": "true",
"accountIdentifier": {
"method": "token",
"value": "158928"
},
"requiresAck": "false",
"metadata": {},
"order": {
"totalAmount": "4.99",
"shippingAmount": "0.00",
"taxAmount": "0.00",
"items": [
{
"name": "Test Product",
"description": "Test Description",
"quantity": "1",
"amount": "4.99",
"sku": "ABA123",
"category": "Test Category",
"refCode": "TestRef",
"imageUrl": "http://www.test.com/item-image.png",
"itemUrl": "http://www.test.com/item"
}
]
}
}
Request parameters
-
originator JSON Object REQUIRED
Shopper information object
-
originator.locationId REQUIRED INTEGER
Store location ID supplied by Zip.
-
originator.deviceRefCode REQUIRED STRING
ID of the device where the transaction is taking place. Pass "null" if not available
-
originator.staffActor JSON Object
ID of the staff who is procesing the trsnsaction. Pass "null" if not available.
-
originator.
staffActor. refCode REQUIRED STRINGID of the staff who is procesing the trsnsaction. Pass "null" if not available.
-
-
-
refCode REQUIRED STRING
Transaction reference ID.
-
payAmount REQUIRED INTEGER
Transaction amount.
-
capture optional BOOLEAN
Defaults to true.
Capture=true
will immediately transfer funds to merchant account and deduct the funds from customers account.Capture=False
will authorize only and will ring-fence funds to be transferred on a call to/capture
-
accountIdentifier JSON Object
Unique transaction autorisation code.
-
accountIdentifier.method REQUIRED STRING
Autorisation type. Supply
token
as default. -
accountIdentifier.value REQUIRED INTEGER
Instore code supplied by customers from their Zip wallet.
-
-
order OPTIONAL JSON Object
Order details object.
-
order.totalAmount REQUIRED INTEGER
Total order amount. Required when order object is included in the request
-
order.shippingAmount OPTIONAL INTEGER
Order shipping amount.
-
order.taxAmount OPTIONAL INTEGER
Order tax amount.
-
order.items OPTIONAL JSON Object
Shipping object.
-
order.
items. name OPTIONAL BOOLEANItem name.
-
order.
items. description OPTIONAL BOOLEANItem description.
-
order.
items. quantity OPTIONAL BOOLEANItem quantity value.
-
order.
items. amount OPTIONAL BOOLEANItem price or amount.
-
order.
items. sku OPTIONAL BOOLEANItem sku.
-
order.
items. category OPTIONAL BOOLEANCateogory of the item.
-
order.
items. refCode OPTIONAL BOOLEANItem reference code or id.
-
order.
items. imageUrl OPTIONAL BOOLEANItem image url.
-
order.
items. itemUrl OPTIONAL BOOLEANItem url.
-
-
-
metadata optional JSON Object
Object containing name value pairs of meta data to be returned whenever recalling this checkout object.