Sitecore Commerce (XC) integration with Zip Pay (Part 1, Solution Design)

Taxonomy: Sitecore

Background (problem statement)

In the past the only available payment options were credit cards and paypal, but things has changed now. There are different payment methods that simplifies the online shopping experience and allows customers to purchase now and pay later or in installment.

One of the major players is the Zip, which has two payment options for the customers to choose from:

 

Zip Pay is an interest free online shopping wallet with a credit limit of up to $1,000, offering the ability to buy now and pay later. Repayments start from as little as $10 a week, or $40 per month.

Zip Money is a line of credit for larger amounts, generally $1,000 and above. Zip Money offers customers a guaranteed 3 months interest-free across all products and up to 48 months with some retailers. The length of the interest-free period varies among individual merchants and is confirmed with the user prior to purchase. For Zip Money accounts greater than $5,000 please consult the merchant you would like to check out with. 

Sitecore Commerce Experience (XC) comes with Braintree integration OOTB which does support both Credit Card and Paypal payments but some of my clients were looking for Zip as an additional payment option to increase their online sale and give a better shopping experience to their customers. Below is a summary of how we did implement Zip integration with Sitecore Commerce

Scope

  • Zip Pay should be available to both desktop and mobile customers
  • A customer is able to select Zip Pay as a payment option in the Payment component on the Cart Page
  • A customer can successfully go through the Zip Pay process of making payment
    • This occurs in a Zip Pay modal over the existing cart page
  • A customer can see the Zip Pay icon in the Order Summary component throughout the checkout process
  • A customer can close the Zip Pay modal at any point during the payment process and return to the Check out page
  • Transaction limits apply per Zip product:
    • Transactions <= $1,000.00 are through Zip Pay
    • Transactions > $1,000.00 are through Zip Money
  • Once Zip Pay has given payment confirmation from their end, the modal will close automatically and the customer will be taken to the order confirmation page via a re-direct of a middle page (customer does not see the re-direct page)
  • Zip Pay "Checkout ID" needs to be captured and stored as part of the Order entity

Assumptions 

First of all, I'm assuming you know how to customize Sitecore Commerce

If a customer chooses to pay via Zip Pay and creates a new Zip Pay account in the modal at the time of payment, they will be required to go through a credit check. Zip pay recommends at least 30 minutes (minimum) before the customer gets a confirmation on the outcome. For new Zip Pay customers they will likely have to restart the checkout process once they have gotten confirmation from Zip Pay

Payment Flow

Zip Pay provides two integration scenarios to complete the payment flow:

  • Full redirect to Zip Pay website landing page
  • Use their javascript client library to complete the payment flow in our website

For consistency with the existing integrated payment provider (Braintree and Paypal), the document hence forth will be leaning towards the javascript checkout client library from ZIP.

Key integration points

Initialize Zip Pay Lightbox modal
Create new checkout
(BE) Create new charge

With a successful checkout object created and only if the checkout object state is approved then we can charge the full payment

  • How we handle a scenario where the checkout state is the following 
    • referred, we could end up with this state if Zip Pay fraud engine has flagged the account creation requires to be manually reviewed.
    • declined, usually because they don't have sufficient balance
      • we won't do anything, the customer can close the modal window and select a different payment option.
    • cancelled, we could end up with this state if the customer has cancelled their payment process through Zip Pay modal dialog
      • we won't do anything, the customer can select a different payment option or click on Zip Pay and continue the checkout process

Brand Guideline

Zip Pay related UI implementation needs to follow their brand guideline.

Brand Guideline For the checkout page, this can be found at https://resources.zip.co/1/marketing/4-receive-your-new-assets
Marketing Assets https://resources.zip.co/1/marketing/digital-and-social-assets

Charge Request Object

Field
Description
authority
authority.type checkout_id
authority.value value of checkout_id
reference Checkout order reference. Pass the order number
amount Checkout order amount
currency Checkout order currency
capture set to true if direct payment or capture the fee immediately

Checkout field mapping

Object
Description
Object
Description
shopper Shopper object
shopper.title Title of shopper (Mr, Mrs, etc). Must be characters of alphabet only, max 20 chars
shopper.first_name First name of shopper. Must be characters of alphabet only, max 50 chars
shopper.last_name Last name of shopper. Must be characters of alphabet only, max 50 chars
shopper.phone Phone number of shopper. Must only be numerals (no spaces, special characters or alphabet chars), max 15 digits
shopper.email Email address of shopper. Must be format of [user]@[domain] (eg; john@example.com.au). 100 chars max
shopper.billing_address Billing address object
shopper.billing_address.line1 Line 1 of the billing address. Alphanumeric + special characters allowed, Max 200 chars
shopper.billing_address.line2 Line 2 of the billing address. Alphanumeric + special characters allowed, Max 200 chars
shopper.billing_address.city City of the billing address. Alphabet characters, spaces and special characters, Max 50 chars
shopper.billing_address.state State of the billing address. Alphabet characters, spaces and special characters, Max 50 chars
shopper.billing_address.postal_code Postal code of the billing address. Alphanumeric, Max 15 chars
shopper.billing_address.country Country of the billing address. Must be “AU” or “NZ”
shopper.billing_address.first_name First name of the billing address
shopper.billing_address.last_name Last name of the billing address
order Order object
order.reference Unique order reference id.
order.amount Total amount of order. This is the amount that is charged to the customer’s zip account. Integer or number to 2.dp (eg; 100.00 or 100)
order.currency Currency (eg; “AUD”, “NZD”)
order.shipping Shipping object
order.shipping.pickup Boolean, true or false. Is this order pickup? OR Click and Collect?
order.shipping.address Shipping address object. Only required if shipping = true.
order.shipping.address.line1 Line 1 of the shipping address. Alphanumeric + special characters allowed, Max 200 chars
order.shipping.address.line2 Line 2 of the shipping address. Alphanumeric + special characters allowed, Max 200 chars
order.shipping.address.city City of the shipping address. Alphabet characters, spaces and special characters, Max 50 chars
order.shipping.address.state State of the shipping address. Alphabet characters, spaces and special characters, Max 50 chars
order.shipping.address.postal_code Postal Code of the shipping address. Alphanumeric, Max 15 chars
order.shipping.address.country Country of the shipping address. Must be “AU” or “NZ”
order.items[] An array of items in the customer’s cart that is being purchased.
order.items[].name Name of the item. Max 500 chars, Alphanumeric and special characters
order.items[].amount Amount of the item. Sum of item amounts, each multiplied by its quantity (next field) must equal amount on the order. Integer or number to 2.dp (eg; 100.00 or 100)
order.items[].quantity Quantity of items of this sku. Integer
order.items[].type Type of item. Values – sku, tax, shipping, discount (NOTE: Add delivery fee as an item)
config Configuration object
config.redirect_uri Redirect URI – where the customer is redirected to following placement of order. Will be an intermediate page that performs order finalization – incl. charging or tokenizing account. Valid URL format, max 500 chars
redirect_uri For some reason the light box checkout library expect this property to be available instead getting the value from config.redirect_uri, could be a library version mismatch

Checkout Response Object

Fields
Description
state

cancelled

declined

referred

completed

approved

order order object
order.reference order number
order.amount order amount
order.currency order currency

Implementation 

First we need to create a feature with ZipPay view

Screen 1

We will then need a storefront API to create checkout. This will call Commerce Engine API to create checkout session

The commerce engine CreateCheckout API will call Zip APIs to create a checkout session. This is for Zip JS library to receive the checkout Id which will then be passed to processing api to settle the payment.

Once the customer clicks on the checkout button (Screen 1) the Zip modal will be displayed, customer then will need to login with their Zip Account and confirm the payment, this will then call the Proccessing end point which will settle the payment by creating a charge.

We will need to add Proccsing end point to our Store front, then add create charge API in our commerce enginer as below

No Comments


Facebook Twitter LinkedIn Google+ Print Email Addthis

Recent Posts

Quick tip: Sitecore XC 903 Certificate issue

TerminatingError(New-SelfSignedCertificate): "CertEnroll::CSignerCertificate::Initialize: Cannot find object or property. 0x80092004 (-2146885628 CRYPT_E_NOT_FOUND)" I've been struggling with this error today and I almost gave up, digging further into the issue I realized that to use the SIF 2.0 I did change the Store Location to LocalMachine& …

Sitecore Commerce (XC) integration with Zip Pay (Part 1, Solution Design)

Background (problem statement) In the past the only available payment options were credit cards and paypal, but things has changed now. There are different payment methods that simplifies the online shopping experience and allows customers to purchase now and pay later or in installment. One of the major players is the Zip, which  …

My Tweets

My Videos