Zip for JavaScript Library

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.

 

Requirements

  • 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.
  • If you don't have one already, you will also need to create a Webservices user role in MyST. This is used for back office operations, such as refunds and transactions updates. Click here to open instructions in a new tab.
  • The integration process requires your system to be configured to send requests using our Webservices API and interpret the responses returned. To learn more about Webservices API, click here to get started.

 

How does it work?

  When configuring your JavaScript Library integration to perform Zip transactions, you will need to set up URL notifications to be sent to your server, to notify when the customer has been redirected to Zip's server to authorisation the payment. We explain how to do this later in this article. After you have received this notification, you can create an order in your own records.

  1. Customer selects Zip on your checkout page.
  2. The JavaScript Library processes an AUTH request to obtain a URL in order to redirect the customer's browser to Zip. At this point, the settlestatus of the AUTH is set to 10 ("Settling") and your system will receive a URL notification to notify of this fact.
  3. The customer's browser is redirected to a checkout environment hosted by Zip, where they are prompted to sign in to their Zip account. Once signed in, the customer can select their preferred credit/debit card on a checkout page hosted by Zip and agree to the payment, before being redirected back to your website.
  4. Once completed, the Zip payment result will be returned with a GET request to your returnurl that contains the unique transactionreference, which can be used to help you display the correct success/error message to the customer.
  5. You will need to use this transactionreference to perform a TRANSACTIONQUERY request with our Webservices API to check the authorisation request has been processed without issue. You should check that the TRANSACTIONQUERY returns settlestatus 0 ("Pending") to indicate that funds will be settled in a batch, typically within 24 hours of authorisation. (settlestatus 3 would indicate the transaction has been cancelled)

Integration overview

  1. Specify a container inside the checkout form to position the Zip APM.
  2. Provide an APM config.
  3. Include all required fields in the JWT payload.
  4. Call APM method from st.js library instance.
  5. Your server must listen for and respond to URL notifications regarding authorisation and settlement.
  6. Your server must send a TRANSACTIONQUERY request using Webservices API and parse the response in order to check the authorisation request has been processed without issue.

 

Configure payment form

The config for Zip is passed as a parameter in the st.APM() method, which is available directly from the st.js library instance.

Please include a container with an id of your choice inside the payment form:
e.g.<div id="container-for-apms"></div>.

Later in the APM config setup, you will need to specify this id under the global placement property.

The method call for Zip payment method will look similar to the below (st.APM(configForZip);):

<html>
<head>
</head>
<body>
<div id="st-notification-frame"></div>
<form id="st-form" action="https://www.example.com" method="POST">
<div id="container-for-apms"></div>
</form>
<script src="https://webservices.securetrading.net/js/v3/st.js"></script>
<script>
(function() {
var st = SecureTrading({
jwt : 'We explain how to construct this on the next page'
});
st.APM(configForZip);
})();
</script>
</body>
</html>

 

Configuration for ZIP APM:

{
placement: 'container-for-apms',
apmList: [
{
name: 'ZIP',
minBaseAmount: 1000,
maxBaseAmount: 10000
}
],
}

 

  Configuration properties Format Description
table-required.png apmList Array of objects A list of APMs to be displayed on screen. Include "ZIP" here to display Zip. Each APM listed must be enabled on your Trust Payments account to be displayed.
table-required.png minBaseAmount Numeric (6)

This determines the minimum payment amount that is required to be signed in the JWT payload before Zip will be displayed as a payment option to the customer.

This field is only used to validate when Zip is displayed on the checkout and does not in itself instruct our system to block transactions from being processed that fall below this amount.

The value specified here needs to be aligned with how your account has been configured on the TRU Connect system. Contact our Support Team to check your configuration and make changes if necessary.

table-required.png maxBaseAmount Numeric (6)

This determines the maximum payment amount that is required to be signed in the JWT payload before Zip will be displayed as a payment option to the customer.

This field is only used to validate when Zip is displayed on the checkout and does not in itself instruct our system to block transactions from being processed that exceed this amount.

The value specified here needs to be aligned with how your account has been configured on the TRU Connect system. Contact our Support Team to check your configuration and make changes if necessary.

table-required.png placement String

The id of a container element, such as <div>

When the APM method is called, Zip will be rendered inside the container.

 

Configure JSON Web Token (JWT) payload

The APM solutions also require a JWT to be specified when initialising the st.js library. The JWT payload must include the following required fields to support APM ZIP.

  JWT Payload fields Format Description
table-required.png accounttypedescription Alpha (20) Value submitted is “ECOM” (represents an e-commerce transaction).
table-required.png baseamount Numeric (13)

Either baseamount or mainamount must be included (not both).

The amount of the transaction in base units (without any decimal places).

e.g. £10.50 would be submitted as “1050”

mainamount Numeric (14)

Either baseamount or mainamount must be included (not both).

The amount of the transaction in main units.
Only include the amount value and the decimal place (no commas).

e.g. £10.99 would be submitted as 10.99
Currencies such as Japanese Yen which do not require a decimal place are submitted without. e.g. 1000 Yen would be 1000.

table-required.png currencyiso3a Alpha (3)

The currency that the transaction was processed in (in ISO3A). Click here for further info.

table-required.png billingcountryiso2a 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 Alphanumeric including
symbols (127)
Billing county.
table-required.png billingemail Email (255) Billing email address.
table-required.png billingfirstname Alphanumeric including
symbols (127)
Billing first name.
table-required.png billinglastname Alphanumeric including
symbols (127)
Billing last name.
table-required.png billingpostcode Alphanumeric (25)

Billing postcode.

table-required.png billingpremise Alphanumeric including
symbols (25)
First line of address.
table-required.png billingstreet Alphanumeric including
symbols (127)
Billing street.
table-required.png billingtown Alphanumeric including
symbols (127)
Billing town.
table-required.png customercountryiso2a Alpha (2)

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

table-required.png customercounty Alphanumeric including
symbols (127)
Delivery address county.
table-required.png customeremail Email (255) Delivery email address.
table-required.png customerfirstname Alphanumeric including
symbols (127)
Delivery address first name.
table-required.png customerlastname Alphanumeric including
symbols (127)
Delivery address last name.
table-required.png customerpostcode Alphanumeric (25) Delivery address postcode.
table-required.png customerpremise Alphanumeric including
symbols (25)
First line of delivery address.
table-required.png customerstreet Alphanumeric including
symbols (127)
Delivery address street.
table-required.png customertown Alphanumeric including
symbols (127)
Delivery address town.
table-required.png returnurl URL (2048)

This is the URL the customer will be redirected to following payment completion. The result of the payment will be returned in a GET request to this endpoint.

table-required.png requesttypedescriptions Alpha (20)

The request types to be processed.

To process a 3-D Secure authenticated payment, submit [“THREEDQUERY”,”AUTH”].

Important: You must ensure “THREEDQUERY” is submitted in this list when performing transactions, in order to ensure 3-D Secure is processed for card payments. This is required by the PSD2 mandate.

table-required.png sitereference Alphanumeric
& underscore (50)
Unique reference that identifies your Trust Payments site.

For further guidance on creating JWTs and optional payload fields, please review our JWT documentation.

 

URL notification following payment

Before you begin testing, you will need to enable a rule which submits URL notifications to your system. You can use these notifications to update your own records as appropriate, and track the progress of orders. Notifications can be configured for the following scenarios:

When payment authorisation initiated (required)
  1. Sign in to MyST.

  2. Search for your sitereference using the search box found at the top of the page.

  3. When viewing your site details, click “Rule manager“.

    webhook-2010-01-en.png

  4. Select the action type “URL notification” from the drop-down and your browser will be redirected.

    webhook-2010-02-en.png

  5. Create a new URL notification rule: webhook-2010-03-en.png
      • (A) Click “Add new condition” and specify the circumstances in which the URL notification is to be triggered following a transaction. Ensure the following options are ticked:
      • (B) Click “Add new action” and specify the endpoint for the URL notification. We recommend including at least the following fields in the Action:
        • Acquirer Response Message (acquirerresponsemessage)
        • Base Amount (baseamount) (e.g. £10.50 is “1050”)*
        • Main Amount (mainamount) (e.g. £10.50 is “10.50”)*
        • *Please choose your preferred format.
        • Billing Country (billingcountryiso2a)
        • Currency (currencyiso3a)
        • Error Code (errorcode)
        • Live Status (livestatus)
        • Order Reference (orderreference)
        • Payment Type (paymenttypedescription)
        • Request Type (requesttypedescription)
        • Settle Status (settlestatus)
        • Site Reference (sitereference)
        • Transaction Reference (transactionreference)
        • Transaction Started Timestamp (transactionstartedtimestamp)
      • (C) Using the drop-down boxes, assign the condition to the action and click “Create rule“.


  6. Ensure the rule is active (this is shown with a tick under the Active column). Once enabled, the rule will be applied to all payment sessions for the given sitereference, and the URL notification will be triggered whenever a Zip transaction is authorised.

    Note: All new rules should be created on your test sitereference and tested to ensure they work as expected before being added to your live sitereference.

  7. You will need to check in the notification received that the settlestatus is “10”, indicating that the payment authorisation process has been initiated and is waiting for the customer to complete the checkout on Zip's servers. After you have received this notification, you can create an order in your own records. You will need to wait for the customer's browser to be redirected to the returnurl, after which your server would process a TRANSACTIONQUERY request to verify the payment result with the Trust Payments gateway, as described below.

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

 

When funds have been settled into your bank account (recommended)

We recommend also 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.

 

 

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 with our Webservices API to establish the current state of the payment.
e.g. 55-9-12345

 

Perform TRANSACTIONQUERY using Webservices API

  The following step requires your system to be configured to send requests using our Webservices API and interpret the responses returned. To learn more about Webservices API, click here to get started.

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 using our Webservices API. You can integrate with our Webservices API using either the Python/PHP SDKs, which will simplify the integration process, or alternatively you can develop your own solution, by following the examples 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

You should check the TRANSACTIONQUERY response has settlestatus 0 ("Pending") to indicate that funds will be settled in a batch, typically within 24 hours of authorisation. (settlestatus 3 would indicate 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"
}

 

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