Zip for Webservices API

zip_logo.svg

Zip is a Buy Now Pay Later (BNPL) payment method based in Australia. This service allows customers to spread the cost of purchases over instalments. When selecting Zip, customers will be prompted to sign in to their Zip account. Once signed in, the customer can select their preferred credit/debit card and agree to the payment, before being redirected back to your website.

  Supported customer countries   GB
  Supported currencies   GBP
  Refunds   Full and partial refunds permitted.
  Chargebacks   Payments are not subject to chargebacks.
  Zero-authorisation

  Not supported.

  Recurring payments

  Not supported.

 

Configuration

You will need to contact your account manager and request that Zip is enabled on your account. A test sandbox account will be provided, which you will need when testing your implementation.

 

Process overview

  1. Initiate the customer
    • Customer agrees to a payment using Zip on the merchant’s website.
    • Merchant submits AUTH request to initiate the session, including returnurl.
    • Merchant receives AUTH response, including redirecturl.
    • Trust Payments updates the settlestatus to 10 (Settling).

  2. Redirect to Zip
    • Merchant redirects the customer’s browser to the redirecturl.
    • Customer follows instructions on Zip's hosted pages to authorise the payment.
    • Once completed, the Zip payment result will be returned with a GET request to your returnurl that contains the unique transactionreference.

  3. Verify payment result 
    • You will need to use the transactionreference included in the returnurl to perform a TRANSACTIONQUERY request to check the authorisation request has been processed without issue. This can be used to help you display the correct success/error message to the customer.
      • When processing with offline settlement (default): You should check that the TRANSACTIONQUERY returns settlestatus 0 ("Pending"). This indicates that funds will be settled in a batch, typically within 24 hours of authorisation.
      • When processing with online settlement: You should check that the TRANSACTIONQUERY returns settlestatus 100 ("Settled"). This indicates that funds have been settled into your bank account.
      • If the TRANSACTIONQUERY returns settlestatus 3 ("Cancelled"), this indicates the transaction has been cancelled.

  4. Settlement
    • Once settled, Trust Payments will submit a URL notification to the merchant’s system as confirmation (needs to be enabled).
    • Merchant receives the notification and responds to inform Trust Payments the notification was received successfully.

 

Authorisation

When the customer chooses to pay with Zip, your system will need to perform an AUTH request and, if successful, redirect the customer’s browser to the URL returned in the response.

 

AUTH request

The example request below is for a Zip AUTH request:

Python PHP cURL Raw JSON Raw XML
#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

auth = {
"currencyiso3a": "GBP",
"requesttypedescription": "AUTH",
"accounttypedescription": "ECOM",
"sitereference": "test_site12345",
"baseamount": "1050",
"paymenttypedescription": "ZIP",
"returnurl": "https://yourwebsite.com",
"billingfirstname": "Joe",
"billinglastname": "Bloggs",
"billingpremise": "123",
"billingstreet": "Test Street",
"billingtown": "Bangor",
"billingcounty": "Gwynedd",
"billingpostcode": "TR45 6ST",
"billingcountryiso2a": "GB",
"billingemail": "customer@customer.com",
"customerfirstname": "Joe",
"customerlastname": "Bloggs",
"customerpremise": "123",
"customerstreet": "Test Street",
"customertown": "Bangor",
"customercounty": "Gwynedd",
"customerpostcode": "TR45 6ST",
"customercountryiso2a": "GB",
"customeremail": "customer@customer.com",
"settlestatus": "0"
}

strequest = securetrading.Request()
strequest.update(auth)
stresponse = st.process(strequest) #stresponse contains the transaction response

Replace <DOMAIN> with a supported domain. Click here for a full list.

 

Field specification

  Field Format Description
table-required.png accounttypedescription
XPath: /operation/accounttypedescription
Alpha (20) Only “ECOM” (e-commerce) is supported.
table-required.png baseamount
XPath: /billing/amount
Numeric (13) The amount of the transaction in base units, with no commas or decimal points, so €10 is submitted as 1000. This value must be greater than zero. (Max length may vary depending on your acquiring bank – Contact your bank for further info)
table-required.png billingcountryiso2a
XPath: /billing/country
Alpha (2)

The country for the customer’s billing address. This will need to be in ISO2A format.

For a list of country codes supported by Zip, refer to the list found at the top of this page.

table-required.png billingcounty
XPath: /billing/county
Alphanumeric including
symbols (127)
Billing county.
table-required.png billingemail
XPath: /billing/email
Email (255) Billing email address.
table-required.png billingfirstname
XPath: /billing/name/first
Alphanumeric including
symbols (127)
Billing first name.
table-required.png billinglastname
XPath: /billing/name/last
Alphanumeric including
symbols (127)
Billing last name.
table-required.png billingpostcode
XPath: /billing/postcode
Alphanumeric (25) Billing postcode.
table-required.png billingpremise
XPath: /billing/premise
Alphanumeric including
symbols (25)
First line of address.
table-required.png billingstreet
XPath: /billing/street
Alphanumeric including
symbols (127)
Billing street.
table-required.png billingtown
XPath: /billing/town
Alphanumeric including
symbols (127)
Billing town.
table-required.png currencyiso3a
XPath: /billing/amount/@currencycode
Alpha (3)

The currency that the transaction will be processed in (in ISO3A format).

For a list of currency codes supported by Zip, refer to the list found at the top of this page.

table-required.png customercountryiso2a
XPath: /customer/country
Alpha (2)

The country for the customer’s delivery address. This will need to be in ISO2A format.

table-required.png customercounty
XPath: /customer/county
Alphanumeric including
symbols (127)

Delivery address county.

table-required.png customeremail
XPath: /customer/email
Email (255)

Delivery email address.

table-required.png customerfirstname
XPath: /customer/name/first
Alphanumeric including
symbols (127)

Delivery address first name.

table-required.png customerlastname
XPath: /customer/name/last
Alphanumeric including
symbols (127)

Delivery address last name.

table-required.png customerpostcode
XPath: /customer/postcode
Alphanumeric (25)

Delivery address postcode.

table-required.png customerpremise
XPath: /customer/premise
Alphanumeric including
symbols (25)

First line of delivery address.

table-required.png customerstreet
XPath: /customer/street
Alphanumeric including
symbols (127)

Delivery address street.

table-required.png customertown
XPath: /customer/town
Alphanumeric including
symbols (127)

Delivery address town.

table-optional.png orderreference
XPath: /merchant/orderreference
Alphanumeric including symbols (25)

 

Recommended length 25 characters or less (exact length dependent on acquiring bank). Failure to adhere to this requirement may result in the text being truncated in the transaction.

Your unique order reference that can be stored on the Trust Payments system.
table-required.png paymenttypedescription
XPath: /billing/payment/@type
Alpha (20) This value must be submitted as “ZIP”.
table-required.png returnurl
XPath: /merchant/returnurl
URL (2048) The URL that the customer will be returned to following a successful authorisation on their Zip account.
table-required.png requesttypedescription
XPath: /@type
Alpha (20) The value in the request must be “AUTH”.
table-optional.png settlestatus
XPath: /settlement/settlestatus
Numeric (3)

Including the settlestatus in your request allows you to choose between offline and online settlement processes:

  • 0 - Offline settlement (default): Funds are settled in daily batches. While transactions are pending settlement, you can update or cancel if needed.
  • 100 - Online settlement: Funds are immediately settled into your bank account.

If the settlestatus is not submitted, the payment is processed as offline settlement by default.

table-required.png sitereference
XPath: /operation/sitereference
Alphanumeric
& underscore (50)
The site reference relates to your individual account which you received on setup. If you do not know your site reference, please contact our Support Team.

 

AUTH response

Your server will need to check the AUTH response returned and redirect the customer's browser to the redirecturl provided.

Python PHP Raw JSON Raw XML
{
u'requestreference': u'An3ug1kap',
u'version': u'1.00',
u'responses': [{
u'splitfinalnumber': u'1',
u'transactionreference': u'23-86-113',
u'merchantname': u'Test Merchant',
u'paymenttypedescription': u'ZIP',
u'settleduedate': u'2017-03-16',
u'baseamount': u'1050',
u'transactionstartedtimestamp': u'2017-03-16 16:25:08',
u'authmethod': u'FINAL',
u'errormessage': u'Ok',
u'settlestatus': u'10',
u'accounttypedescription': u'ECOM',
u'errorcode': u'0',
u'redirecturl': u'https://example.com',
u'acquirertransactionreference': u'12',
u'requesttypedescription': u'AUTH',
u'operatorname': u'webservices@example.com',
u'livestatus': u'0',
u'currencyiso3a': u'GBP'
}]
}

 

Field specification

The time the transaction was processed.

  Field Format Description
table-returned.png accounttypedescription
XPath: /operation/accounttypedescription
Alpha (20) The value returned is “ECOM”.
table-returned.png acquirertransactionreference
XPath: /acquirertransactionreference
Alphanumeric including symbols (127) Unique transaction reference assigned by Zip.
table-conditional.png authmethod
XPath: /operation/authmethod
Alpha (11)

Auth methods are used to specify how a transaction is to be processed by the card issuer. The following values can be returned:

This field is returned if submitted in the request.

table-returned.png baseamount
XPath: /billing/amount
Numeric (13) The amount of the transaction in base units, with no commas or decimal points, so €10 is returned as 1000.
table-returned.png currencyiso3a
XPath: /billing/amount/@currencycode
Alpha (3)

The currency that the transaction was processed in (in ISO3A format).

For a list of currency codes supported by Zip, refer to the list found at the top of this page.

table-returned.png errorcode
XPath: /error/code
Numeric (1-5) The error code should be used to determine if the request was successful or not.
  • If the error code is “0” then the transaction was successful.
  • If the error code is not “0” then the transaction was not successful.

Click here for a full list of errorcode and message values.

table-conditional.png errordata
XPath: /error/data
Alphanumeric (255) Additional information to help troubleshoot the error.
table-returned.png errormessage
XPath: /error/message
Alphanumeric (255) This is the corresponding message to the above code.

Click here for a full list of errorcode and message values.

table-returned.png livestatus
XPath: /live
Numeric (1)
  • 0 – Transaction processed using a test account.
  • 1 – Transaction processed using a live account.
table-returned.png merchantname
XPath: /merchant/merchantname
Alphanumeric (255)

These are details associated with the account used to process the transaction.

To amend these fields, please contact our Support Team.

table-returned.png operatorname
XPath: /merchant/operatorname
Alphanumeric (255) The value of this field contains the name of the user that processed the request.
table-returned.png paymenttypedescription
XPath: /billing/payment/@type
Alpha (20) This value returned is “ZIP”.
table-returned.png redirecturl
XPath: /other/redirecturl
URL (255) Redirect the customer’s browser to this URL to allow them to complete the payment on Zip's hosted pages.
table-returned.png requesttypedescription
XPath: /@type
Alpha (20) The value returned is “AUTH”.
table-returned.png settleduedate
XPath: /settlement/settleduedate
Date YYYY-MM-DD The date on which the transaction will be settled.
table-returned.png settlestatus
XPath: /settlement/settlestatus
Numeric (3) This should be returned with value 10 (Settling) in the AUTH response.
table-returned.png

splitfinalnumber
XPath: /operation/splitfinalnumber

Numeric (2) This will be returned with value 1.
table-returned.png transactionreference
XPath: /transactionreference
Alphanumeric including
hyphens (25)
A unique reference for the transaction assigned by Trust Payments.
table-returned.png transactionstartedtimestamp
XPath: /timestamp
Date time YYYY-MM-DD hh:mm:ss The time the transaction was processed.

 

Customer redirect following payment

Following the payment completion, the customer will be redirected to the returnurl you specified in the APM config. Your system will be returned a GET request containing the unique transactionreference associated with the Zip payment, as described below:

  Field Format Description
table-returned.png transactionreference Alphanumeric including
hyphens (25)
Unique reference of the transaction, available after a payment request has been processed. You will need to use this in a subsequent TRANSACTIONQUERY request to establish the current state of the payment.
e.g. 55-9-12345

 

Perform TRANSACTIONQUERY using Webservices API

At this stage in the process, the customer will have been redirected to the returnurl and your server will need to verify the result by sending a TRANSACTIONQUERY request, as shown below:

 

Request example

Python PHP cURL Raw JSON Raw XML
#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

query = {
"requesttypedescriptions": ["TRANSACTIONQUERY"],
"filter":{
"sitereference": [{"value":"test_site12345"}],
"transactionreference": [{"value":"55-9-12345"}]
}
}

strequest = securetrading.Request()
strequest.update(query)
stresponse = st.process(strequest) #stresponse contains the transaction response

Replace <DOMAIN> with a supported domain. Click here for a full list.

 

Request field specification

  Field Format Description
table-required.png sitereference
XPath: /filter/sitereference
Alpha (50) The site reference that processed the transaction.
table-required.png transactionreference
XPath: /filter/transactionreference
Alphanumeric including hyphens (25) The unique reference associated with the Zip transaction.

 

Response

  • When processing with offline settlement (default): You should check that the TRANSACTIONQUERY returns settlestatus 0 ("Pending"). This indicates that funds will be settled in a batch, typically within 24 hours of authorisation.
  • When processing with online settlement: You should check that the TRANSACTIONQUERY returns settlestatus 100 ("Settled"). This indicates that funds have been settled into your bank account.
  • If the TRANSACTIONQUERY returns settlestatus 3 ("Cancelled"), this indicates the transaction has been cancelled.

The TRANSACTIONQUERY response also contains the transactionreference and orderreference, which you can use to correctly identify the transaction, allowing you to update the order in your own records.

Raw JSON
{
"requestreference": "W57-4r9dhbtx",
"version": "1.00",
"response": [
{
"transactionstartedtimestamp": "2021-11-29 14:12:45",
"errormessage": "Ok",
"errorcode": "0",
"records": [
{
"authmethod": "FINAL",
"billingcounty": "Gwynedd",
"transactionstartedtimestamp": "2021-11-29 14:10:04",
"sitereference": "test_site12345",
"billingstreet": "Test Street",
"transactionreference": "57-97-146",
"billingcountryiso2a": "GB",
"billingemail": "test@test.com",
"billingfirstname": "Joe",
"livestatus": "0",
"splitfinalnumber": "1",
"settleduedate": "2021-11-29",
"billingpremise": "123",
"errorcode": "0",
"baseamount": "2000",
"billingtown": "Bangor",
"acquirertransactionreference": "05b3f4d0-feba-4c49-b97f-f126b5871f21",
"billingpostcode": "TR45 6ST",
"merchantname": "Merchant test site",
"paymenttypedescription": "ZIP",
"orderreference": "MyOrder123",
"settledtimestamp": "2021-11-29 14:10:04",
"accounttypedescription": "ECOM",
"updatereason": "stgateway",
"requesttypedescription": "AUTH",
"customerip": "1.2.3.4",
"currencyiso3a": "GBP",
"billinglastname": "Bloggs",
"settlebaseamount": "2000",
"errormessage": "Ok",
"interface": "JWT-JWT-JWT",
"operatorname": "webservices@example.com",
"settlestatus": "0",
"customercountryiso2a": "GB",
"customercounty": "Gwynedd",
"customeremail": "test@test.com",
"customerfirstname": "Joe",
"customerlastname": "Bloggs",
"customerpostcode": "TR45 6ST",
"customerpremise": "123",
"customerstreet": "Test Street",
"customertown": "Bangor"
}
],
"found": "1",
"requesttypedescription": "TRANSACTIONQUERY"
}
],
"secrand": "lN"
}

 

URL notification following payment

We recommend configuring URL notifications that are sent to your system when Zip transactions are settled. In order to configure this, you will need to contact our Support Team and request this is enabled on your account. As part of this process, please request for the following fields to be returned in this notification:

  • Settle Status (settlestatus)
  • Site Reference (sitereference)
  • Transaction Reference (transactionreference)

You will need to check the notification received. If the settlestatus is “100”, this indicates that the funds have been settled. However, a value of “3” indicates there has been a problem and the payment was subsequently cancelled.

You must configure your system to respond to all URL notifications received from Trust Payments with an HTTP 200 OK response.
For example: “HTTP/1.0 200 OK”.
Your system must reply within 8 seconds of receiving a notification.

 

Testing

You will need to test your solution before you can begin processing live payments. Test transactions are processed through your test Site Reference.

  Requirements

You will need to contact our Support Team, providing your Zip test account details. We will then configure your test site reference to connect directly to the Zip testing environment.

When performing test transactions, you will be redirected to the Zip testing environment to simulate a payment. The process you will follow is exactly the same as when processing live payments. As part of this process, Zip will prompt you to enter a real mobile phone number that you will need in order to complete two-factor authentication.

 

Refunds

After processing a payment with Zip, it is possible to pay the customer back by submitting a REFUND request. Full and partial refunds are supported.

Refunds for Zip are settled immediately (settlestatus “100”).

 

Requirements

  • You cannot refund a payment until the AUTH has been settled (settlestatus is “100”).
  • You cannot refund a greater amount than was originally settled.

The REFUND request and response for Zip payments follow the same field specification as outlined in our standard REFUND documentation. Click here for further information.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request