Home
API Reference

Purchase requests

POST

/purchaserequests

https://[api-endpoint-environment]/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 Flow

A 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.

RequiresAck

The requiresAck field is an optional boolean that defaults to false.

If requiresAck is set to true, the customer will not be notified of the completed transaction until the purchase request has been explicitly acknowledged by a successful call to the /ack endpoint. This allows merchants to control the timing of customer notifications, ensuring that internal systems have processed the transaction before the customer is alerted.

{
  "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 transaction. Pass "null" if not available.

      • originator.staffActor.refCode REQUIRED STRING

        ID 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

  • requiresAck optional BOOLEAN

    Defaults to false. requiresAck=false will immediately notify the customer of the completed transaction when the orders is completed with Zip. requiresAck=true will ensure the customer is not be notified of the completed transaction until the purchase request has been explicitly acknowledged by a successful call to the /ack endpoint.

  • 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 BOOLEAN

        Item name.

      • order.items.description OPTIONAL BOOLEAN

        Item description.

      • order.items.quantity OPTIONAL BOOLEAN

        Item quantity value.

      • order.items.amount OPTIONAL BOOLEAN

        Item price or amount.

      • order.items.sku OPTIONAL BOOLEAN

        Item sku.

      • order.items.category OPTIONAL BOOLEAN

        Cateogory of the item.

      • order.items.refCode OPTIONAL BOOLEAN

        Item reference code or id.

      • order.items.imageUrl OPTIONAL BOOLEAN

        Item image url.

      • order.items.itemUrl OPTIONAL BOOLEAN

        Item url.

  • metadata optional JSON Object

    Object containing name value pairs of meta data to be returned whenever recalling this checkout object.