Zip for Android SDK

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?

  1. Customer selects Zip on your checkout page.
  2. The Android SDK 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 checkout environment hosted by Zip is displayed in a web-view within the app, 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 payment SDK will close the web-view and return the response JWT from the gateway for the AUTH, along with additional results data, transactionreference and the settlestatus, 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)

There are two integration methods that we support when configuring Zip as part of your mobile payment solution:

  • Method 1: This solution requires you to handle the creation of UI components, such as the Zip payment button, and ensure all required methods are called to initiate the Zip transaction.
  • Method 2: This solution uses the Drop-In payment form view to render UI components and handle the vast majority of the payment flow. (Click here to scroll down to relevant section)

 

Integrating with Method 1

This solution requires you to handle the creation of UI components, such as the Zip payment button, and ensure all required methods are called to initiate the Zip transaction.

  1. Render a button that has the Zip logo, providing the requirements for doing so have been met.

      Refer to Zip's Brand Assets page for resources and advice regarding button appearance.

    Before your app displays the Zip button, the following requirements must be met:

    • All required fields specified in the table below must be included in the JWT payload.
    • The baseamount or mainamount specified within the signed payload created must fall within the min and max Zip amount, which was agreed with the Trust Payments Support Team.
    • The requesttypedescriptions field must only be one of the following combinations:
      • [AUTH]

      • [THREEDQUERY, AUTH]

      • [THREEDQUERY, AUTH, RISKDEC]

      ACCOUNTCHECK or SUBSCRIPTION cannot be included in the requesttypedescriptions field because they are not features supported by Zip.


  2. On your secure server, you will need to generate a signed JWT with the following required fields:

      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 requesttypedescriptions Alpha (20)

    The request types to be processed.

    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.
    table-required.png termurl URL (1024)

    Required for 3-D Secure authentication with card payments.


    This URL is used to instruct the card issuer where to send the customer’s browser after they have been authenticated on the card issuer’s ACS. You must submit the following URL in this field when performing 3-D Secure:

    https://payments.securetrading.net/
    process/payments/mobilesdklistener


  3. Create an instance of paymentTransactionManager.

    For guidance on how to use the payment transaction manager API to perform a payment request to Trust Payments, please refer to the "Payment Transaction Manager" on the Getting started with Android SDK page.

    The above guide will refer to a set of examples you can review in our GitLab repository. One of the examples for Zip can be found here. You will require the JWT created in step two when calling method createSession on the paymentTransactionManager instance to create the paymentSession.


  4. When the customer taps the Zip button, your application will need to detect this interaction and on the instance of the payment manager, call the performAPMTransaction() method, as shown in the following example:

    paymentTransactionManager.performAPMTransaction(
    paymentSession, APM.ZIP, { this }, ActivityResultProvider()
    )

    When calling this method the SDK will submit an AUTH request to the Trust Payments gateway, which initiates the transaction process and retrieves the URL to which the customer will be redirected inside of a web-view.


  5. You will need to enable a rule which submits URL notifications to your system. During the Zip payment process, your server must listen for and respond to URL notifications regarding authorisation and settlement. 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)

    Follow the steps below to configure a URL notification that is triggered when the authorisation process has been initiated:

    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.

    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.


  6. The Zip checkout page is displayed in a web-view, the customer signs into their account and confirms their order.

    zip-android-0702-en.png

    The Zip checkout is displayed in a web view. You can customise the header title by passing it as a parameter in APMConfiguration:

    private val apmConfiguration = APMConfiguration(
    supportedAPMs = listOf(APM.ZIP),
    headerTitle = "Custom title"
    )
    paymentTransactionManager.performAPMTransaction(
    paymentSession, APM.ZIP, { this }, ActivityResultProvider(),
    apmConfiguration.header)

  7. The payment SDK will close the web-view and in the result you will receive the PaymentTransactionManger.Response object, which will contain the JWT from the gateway for the AUTH, along with additional results data, transactionreference and the settlestatus, which can be used to help you display the correct success/error message to the customer.

    data class Response(
    val responseJwtList: List<String> = emptyList(),
    val additionalTransactionResult: AdditionalTransactionResult? = null,
    val error: Error? = null
    )
    val result: PaymentTransactionManager.Response = paymentTransactionManager.performAPMTransaction(
    paymentSession, APM.ZIP, { runBlocking { requireActivity() } },
    currentActivityResultProvider as ActivityResultProvider,
    headerTitle = apmConfiguration.headerTitle
    )
    val settleStatus = result.additionalTransactionResult?.settleStatus
    val transactionReference = result.additionalTransactionResult?.transactionReference

    The following fields are included in the JWT:

      Field Format Description
    table-returned.png settlestatus Numeric (3) This should be returned with value 10 (Settling) in the AUTH response.
    table-returned.png transactionreference Alphanumeric including
    hyphens (25)
    A unique reference for the transaction assigned by Trust Payments.

  8. Your server must submit a TRANSACTIONQUERY request using Webservices API and parse the response in order to check the transaction has been processed with Zip without issue.

      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.

    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"
    }

 

Integrating with Method 2

Use the Drop-In View to render UI and handle payment logic

This solution uses the Drop-In payment view to render UI components and handle the vast majority of the payment flow.

  1. Configure APMConfiguration to include Zip as a supported APM, while also specifying the zipMinAmount and zipMaxAmount, as shown in the example below:

    private val apmConfiguration = APMConfiguration(
    supportedAPMs = listOf(APM.ZIP),
    zipMinAmount = 10.0,
    zipMaxAmount = 100.0
    )
      The baseamount or  mainamount specified within the signed payload created must fall within the min and max Zip amount, which was agreed with the Trust Payments Support Team.

  2. On your secure server, you will need to generate a signed JWT with the following required fields:

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

  3. For merchants unfamiliar with our Drop-in payment view, we recommend you review the following Getting started resource. Once you have a better understanding of our Drop-in solution, you can use the following example in order to include Zip in to the pre-built UI.

    private val apmConfiguration = APMConfiguration(
    supportedAPMs = listOf(APM.ZIP),
    zipMinAmount = 10.0,
    zipMaxAmount = 100.0
    )

    dropInPaymentView.dropInZipPaymentViewListener = this
    dropInPaymentView.validateZipButtonVisibility(
    jwtToken, apmConfiguration
    );

    override fun onZipButtonClicked() {
    paymentTransactionManager.performAPMTransaction(
    paymentSession, APM.ZIP, { this }, ActivityResultProvider(),
    apmConfiguration.header
    )
    }

  4. A button with the Zip logo is rendered on the checkout, providing the transaction amount falls within the zipMinAmount and zipMaxAmount signed in the JWT payload, and providing the following conditions for a Zip transaction to be processed have been met:

    • All required fields specified in the table above must be included in the JWT payload.
    • The baseamount or mainamount specified within the signed JWT payload must fall within the zipMinAmount and zipMaxAmount specified in the APMConfiguration parameters. The amount values specified in the APMConfiguration parameters must align with those agreed with the Trust Payments Support Team.
    • The requesttypedescriptions field must only be one of the following combinations:
      • [AUTH]

      • [THREEDQUERY, AUTH]

      • [THREEDQUERY, AUTH, RISKDEC]

      ACCOUNTCHECK or SUBSCRIPTION cannot be included in the requesttypedescriptions field because they are not features supported by Zip.

    Customising Zip button appearance on the Drop-In View

    The following is an example of how to customise the appearance of the Zip payment button in your XML file:

    <com.trustpayments.mobile.ui.dropin.DropInPaymentView
    android:id="@+id/dropInPaymentView"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:zipButtonBackgroundColor=""
    app:zipButtonBorderColor=""
    app:zipButtonBorderWidth=""
    app:zipButtonCornerRadius=""
    app:zipButtonDisabledBackgroundColor=""
    app:zipButtonPaddingBottom=""
    app:zipButtonPaddingLeft=""
    app:zipButtonPaddingRight=""
    app:zipButtonPaddingTop=""
    app:zipButtonPressedBackgroundColor=""
    app:zipButtonTextColor=""
    app:zipButtonTextSize=""/>

  5. When the customer taps the Zip button, an AUTH request is submitted to the Trust Payments gateway, which initiates the transaction process and retrieves the URL to which the customer will be redirected.


  6. You will need to enable a rule which submits URL notifications to your system. During the Zip payment process, your server must listen for and respond to URL notifications regarding authorisation and settlement. 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)

    Follow the steps below to configure a URL notification that is triggered when the authorisation process has been initiated:

    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.

    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.


  7. The Zip checkout page is displayed in a web-view, the customer signs into their account and confirms their order.

    zip-android-0702-en.png

    The Zip checkout is displayed in a web view. You can customise the header title by passing it as a parameter in APMConfiguration:

    private val apmConfiguration = APMConfiguration(
    supportedAPMs = listOf(APM.ZIP),
    zipMinAmount = 10.0,
    zipMaxAmount = 100.0,
    headerTitle = "Custom title"
    )

  8. The payment SDK will close the web-view and in the result you will receive the response JWT from the gateway for the AUTH, along with additional results data, transactionreference and the settlestatus, which can be used to help you display the correct success/error message to the customer.

    data class Response(
    val responseJwtList: List<String> = emptyList(),
    val additionalTransactionResult: AdditionalTransactionResult? = null,
    val error: Error? = null
    )
    val result: PaymentTransactionManager.Response = paymentTransactionManager.performAPMTransaction(
    paymentSession, APM.ZIP, { runBlocking { requireActivity() } },
    currentActivityResultProvider as ActivityResultProvider,
    headerTitle = apmConfiguration.headerTitle
    )
    val settleStatus = result.additionalTransactionResult?.settleStatus
    val transactionReference = result.additionalTransactionResult?.transactionReference

    The following fields are included in the JWT:

      Field Format Description
    table-returned.png settlestatus Numeric (3) This should be returned with value 10 (Settling) in the AUTH response.
    table-returned.png transactionreference Alphanumeric including
    hyphens (25)
    A unique reference for the transaction assigned by Trust Payments.

  9. Your server must submit a TRANSACTIONQUERY request using Webservices API and parse the response in order to check the transaction has been processed with Zip without issue.

      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.

    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"
    }
    ],
    "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