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. 
{
  "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 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

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