Zip
Introduction
Zip is a credit payment provider that allows customers to spread the cost of their order value over multiple payments. Aurora's integration with Zip allows your customers to make use of Zip's payment plans when placing orders via the Aurora Front-end.
Initial Setup
The Zip Integration uses the Aurora Microservice (MS) framework, and as such must be set-up in advance by Aurora Commerce before you can use it with your store.
Doing this requires a one-off development to setup and configure your store to use the Zip MS, after which, you can then configure the integration at your own leisure.
If you have not yet had (or do not know if you have had) the Zip MS set up and configured for your store, then please contact Aurora Commerce for more details regarding how to get this done.
In order to configure your Zip MS, you will need to request the following details from Zip:
| Request from Zip | Detail |
|---|---|
| Zip API Key | This needs to be requested from Zip for the global API. The API key within the merchant account settings will not work. |
| Payment flow | This will either be “Immediate Capture” (PAYMENT) or “Auth and Capture” (RELEASE). This will need to be set within the MS settings and must reflect the account type set up with Zip (Please see the settings under the section Enable the Zip Microservice). |
Please request these details for both Staging (Sandbox) and Production (Live) environments, so that you can test your integration before go live.
Aurora Backend Settings
The Zip payment options are not usable when placing new orders using the Orders > New Order section of the Aurora Back-end. It may only be used by the customer during checkout on the Front-end.
This section describes how to configure the Zip integration for use on your Store's Front-end once it has been enabled for use on your Store(s).
Once the Zip integration has been enabled for your Store(s) to use, which is a process that requires you to contact your Agency to complete, you can follow these steps to allow your customers to use it on your Store(s) checkout.
Enable the Zip Microservice
Store > Settings > Feeds > Microservice > Proxy Zip
Configure visibility of the Zip payment option (in conjunction with the "Payment Types Accepted at Checkout" setting):
| Parameter Name | Value for Integration | Note |
|---|---|---|
| Enabled? | checked | Controls whether the Zip payment option is visible on your checkout page: checked = accessible and visible unchecked = not accessible and not visible |
Payment Types Accepted at Checkout
Store > Settings > Payment Providers
Configure Aurora to accept orders using the Zip payment type:
| Parameter Name | Value For Integration | Note |
|---|---|---|
| Zip Payments | checked | Controls whether Zip is on the list of payment types that will be accepted on checkout submission. checked = Zip is accepted and visible on checkout submission unchecked = Zip is not accepted and not visible on checkout submission |
| Validate Payment Type | checked | Controls whether the checkout enforces a strict/reduced list of payment types that are accepted on checkout submission. checked = payment types are enforced to the defined list unchecked = payment types are not enforced to the defined list |
This 'visibility behaviour' is enforced entirely within the Aurora Front-end Templates and so is the default behaviour offered by the Aurora Demo Example Front-end Templates, but may not be how your own Front-end Templates are configured.
If you run into issues with payment option visibility, please check your Front-end Templates for the appropriate logic.
Microservice Settings
Aurora currently only uses the Zip Global API Endpoint.
The Zip settings (including your Zip API Account details) are configured from the Store > Plugins > Zip > Configure section of the Aurora Back-end. This page controls the settings used by Aurora to contact the Zip service.
| Parameter Name | Value for Integration | Notes |
|---|---|---|
| Is Live | Checked - for Live Unchecked - for Sandbox | This controls whether the sandbox mode is enabled for testing the integration. checked = sandbox mode is not enabled and real payments will be taken unchecked = sandbox mode is enabled and real payments will not be taken |
| Payment Type | PAYMENT - Takes payment immediately on order placement. DEFERRED - Only Defers/Authorises payment on order placement. | When using the DEFERRED method, payment must be captured at some point later in your order lifecycle, e.g. during dispatch, which Aurora supports doing automatically for you, should you wish to do this. The Zip merchant account must be set up correctly for these different flows: PAYMENT → Immediate Capture DEFERRED → Auth and Capture |
| Live API Key | Example value (do not use): abc.123.xyz | Merchant API Key for live environments. Contact Zip for this Key directly if using the Global API. It is not the API key that is found within the Zip merchant settings. |
| Sandbox API Key | Example value (do not use): abc.123.xyz | Merchant API Key for sandbox environments. Contact Zip for this Key directly if using the Global API. It is not the API key that is found within the Zip merchant settings. |
| Aurora API Endpoint | Example value (do not use):https://api.aurorademo.com | API endpoint for Aurora instance to collect product data. |
| Aurora API Version | 1.5 | Choose which Aurora API version to be used. It is recommended that you do not use 'head' as this is subject to changes, that could render your integration inoperable on update. Changing this version number should be done with care and the Zip checkout process tested in full whenever done to ensure it is still operating as expected. |
| Aurora API Token | super_secret_token | Add your Aurora API token. Required methods for the API user are: SiteTextGet (used for validating access to the API) Optional methods for the API user are: ProductGet (used to include the Product URL and Image in Zip). It is recommended that the Zip integration is issued with its own dedicated Aurora API Token to allow more secure control over its use. Please see Aurora API User Management for more detail regarding how to manage your Aurora API Users and their Tokens. |
| HTTP Auth User | Example value (do not use): http_username | Add your HTTP Auth User for the HTTP authentication. Use when there is HTTP authentication. For example all Test instances are secured with HTTP authentication. |
| HTTP Auth Password | Example value (do not use): http_password | Add your HTTP Auth Password for the HTTP authentication. Use when there is HTTP authentication. For example all Test instances are secured with HTTP authentication. |
Aurora Service Errors
Content > Site Text
User error messages from the Aurora payment service that can be changed and translated using the Aurora Site Text system:
| Page | Part | Note |
|---|---|---|
| Checkout | CheckoutPayment proxy-zippay Error: MSRequestInvalid | A general error when a request to the payment service cannot be provided. This may be resolvable if the user tries the operation again. |
| Checkout | CheckoutPayment proxy-zippay Error: MSResponseInvalid | A general error when a response from the payment service cannot be provided. This may be resolvable if the user tries the operation again. |
| Checkout | CheckoutPayment proxy-zippay Error: MSConfigurationError | The Zip MS has not been configured correctly and is unable to connect to the Zip API. |
| Checkout | CheckoutPayment proxy-zippay Error: MSPaymentProviderError | The Zip API has responded with an unknown error. More details on these errors can be found within: Tools > Logs > API Integration Log |
| Checkout | CheckoutPayment proxy-zippay Error: MSPaymentProviderConnectionError | The Aurora Zip service was unable to connect to the Zip API. More details on these errors can be found within: Tools > Logs > API Integration Log |
| Checkout | CheckoutPayment proxy-zippay Error: MSPaymentRedirectError | The Zip API returned an error when we tried to generate a redirect URL for the user. More details on these errors can be found within: Tools > Logs > API Integration Log |
| Checkout | CheckoutPayment proxy-zippay Error: MSPaymentCancelled | The customer cancelled payment within Zip and was returned to checkout. |
| Checkout | CheckoutPayment proxy-zippay Error: MSPaymentDeclined | The customers payment request was declined by Zip and was returned to checkout. |
| Checkout | CheckoutPayment proxy-zippay Error: MSVoidFailed | The Zip API returned an error when we tried to void the payment. More details on these errors can be found within: Tools > Logs > API Integration Log |
| Checkout | CheckoutPayment proxy-zippay Error: MSVoidFailed_PartialRelease | The Void failed as the payment has been partially released. |
| Checkout | CheckoutPayment proxy-zippay Error: MSReleaseFailed | The Zip API returned an error when we tried to release the deferred payment. More details on these errors can be found within: Tools > Logs > API Integration Log |
| Checkout | CheckoutPayment proxy-zippay Error: MSRefundFailed | The Zip API returned an error when we tried to refund the payment. More details on these errors can be found within: Tools > Logs > API Integration Log |
Frontend Template Integration
Displaying the Zip Payment Option
In order to use the Zip MS within your checkout, you must simply include the following values within your checkout submission:
| Name | Value |
|---|---|
| payment_type | proxy-zippay |
Example template:
{if $config.microservice_proxyzippay_live}
{include file="checkout/zippay/payment-methods.tpl.html"}
{/if}
Find the content of the "checkout/zippay/payment-methods.tpl.html" file within the Aurora Demo Example Front-end Templates.
Gotchas
Payment Flow
As mentioned previously in this document, Zip must set up the payment type to match the setting in Auroras Zip plugin settings.
The merchant needs to contact Zip when setting up the integration to set this as follows:
PAYMENT → Zip merchant account must be on “Immediate capture workflow”
RELEASE → Zip merchant account must be on “Authorise and capture workflow“
The plugin has no way to detect which payment flow the merchant account is on.
Merchant account delay
Orders created in Aurora can take several minutes to appear in the merchant dashboard.
Voiding transactions
Zip does not allow voiding a transaction which has had a partial release.
Notes for Testing
When testing the Zip integration, you should keep the following in mind.
SMS Mobile Phone Verification
During testing, Zip sends an SMS for verification. There is currently no mechanism to bypass this in their sandbox environment so a number must be given to which you have access to.
Dummy card details
During testing you may use the following card details to test a checkout.
| Card Number | Expiry | CVV |
|---|---|---|
| 4000 0566 5566 5556 | 02/22 | 222 |
Updated over 2 years ago