Skip to main content

Direct Integration for Instore

Introduction#

The quickest way to implement instore Interest Free shopping is to integrate with Latitude Checkout from the point of sale.

Leveraging a series of UX-designed screens, Latitude Checkout enables an SMS to be sent to the Customer’s mobile number. A payment link will direct the Customer to a hosted payment page. The Customer can then enter their card/account details. The POS can poll for the payment outcome via Latitude APIs using 2 supported methods.

As a fallback, when the Customer is unable to receive the SMS, Latitude Checkout will provide alternative manual payment URL, where the Sales Staff can initiate ‘manual payment’ to render the Latitude Checkout payment page. The Sales Staff will then enter the Customer’s card/account details into the hosted payment page


Scope#

The release of this document will provide details on:

  • integrations for instore Point of Sale
  • for Merchants who are Instant Settlement
    * accepting the payment (purchase)
    * accepting the refund (partial and full)
  • for Merchants who are Deferred Settlement
    * accepting the payment (authorisation)
    * order management requests for partial/full refund, partial/full void and partial/full capture
  • auto capture features

Note: For Settlement Method definitions, please refer to Terminology.


Setup Pre-requisite Requirements#

Merchant IDAuthorised Direct Merchants are identified by Latitude using a unique Merchant Identifier.
For instore integration, the merchant ID will be at store level.

If you have not received your Merchant ID or Merchant Secret please contact your Latitude Financial Services representative.
Merchant SecretAuthorised Direct Merchants use the Merchant Secret for basic authentication in all request messages.
For instore integration, the merchant secret will be at store level.

If you have not received your Merchant ID or Merchant Secret please contact your Latitude Financial Services representative.
Store Merchant ID (storeMid)Unique 9 digits identification for each store provided by Latitude. It is for settlement purpose e.g. 000400100

If you have not received the Store Merchant IDs, please contact your Latitude Account Manager

API Endpoints#

Latitude payment endpoints for authorisation/purchase requests (POST)

EnvironmentEndpoint
Test/Sandboxhttps://api.test.latitudefinancial.com/v1/applybuy-checkout-service/purchase
Productionhttps://api.latitudefinancial.com/v1/applybuy-checkout-service/purchase

Latitude payment endpoints for status requests (GET) (the payment outcome can be obtained using either status request, or the statusUrl)

EnvironmentEndpoint
Test/Sandboxhttps://api.test.latitudefinancial.com/v1/applybuy-checkout-service/purchase/{gatewayReference}/status
Productionhttps://api.latitudefinancial.com/v1/applybuy-checkout-service/purchase/{gatewayReference}/status

Integration Flow#

StepDetailExample Screens
1The Sales Staff interfaces with the POS screens.
The Sales Staff will tender the sale with Latitude Interest Free as the payment option
integration flow icon
2The POS sends Purchase Request to Latitude’s API endpoint (note: platformType=instore-pos)
3The Sales Staff will be shown Latitude Checkout’s Merchant Order Summary form.
1. Select the appropriate plan from the dropdown list.
2. Enter the Customer’s mobile number

Latitude Checkout Session will time out after 10 minutes

Note:
"result": "submitted"
integration flow icon
4Once the Customer’s mobile has passed format validation, the form will provide the "action" buttons.
Sales Staff can select the send payment link (via SMS) to the Customer

Latitude Checkout Session will time out after 10 minutes

Note:
"result": "submitted"
integration flow icon
5Whilst the Customer is waiting for the SMS or performing payment on their mobile device, the POS can poll Latitude Checkout for the result via 2 available methods:
a. integrate with Latitude API to send the Status Request
b. poll using the statusUrl that has been returned in Purchase Response

Note:
"result": "initiated" indicates that the customer has clicked the payment link and the payment page is loaded
integration flow icon
6Once the payment is completed, Latitude Checkout will display the payment result page. By this time, the POS has received confirmation of the payment’s status (i.e. completed or failed), and can therefore stop polling. The POS should close the Latitude Checkout screen

Note:
"result": "completed" if the payment is successful or "result": "failed" if declined
integration flow icon
7The POS will notify the Sales Staff with an appropriate message/prompt (and the order is updated) on the POS
8If the Customer did not receive the SMS or could not complete the payment on their mobile device (during step 5), the Sales Staff can select Manual Payment button to invoke the **manualPaymentUrl

Note:
"result": "submitted"
integration flow icon
9Manual payment will display the Latitude payment form. Sales Staff can enter the Customer’s card/account details and submit the payment

Note:
"result": "initiated"
integration flow icon
10When the payment has been submitted, the POS can poll Latitude Checkout (status request) for the result

Upon receiving the status response of completed or failed, the POS can close the Latitude Checkout screen and notify the Sales Staff with an appropriate message/prompt (and the order is updated) on the POS

Note:
"result": "completed" if the payment is successful or "result": "failed" if declined
integration flow icon
11Recommendations- Ensure a timeout is set on the POS during the polling for the payment outcome.
- If the Latitude Checkout screen is accidently closed, ensure that the POS polling is stopped (or can be stopped). Sales Staff must be able to re-tender the same order with Latitude Interest Free
- The POS should close the Latitude Checkout screen when the payment is completed i.e. when result is either "completed" or "failed"
- Merchant partners are responsible for the POS UX designs, and control the positional layout of the Latitude Checkout frames
- Once the payment outcome has been received, Merchant partners can display the appropriate POS message to the Sales Staff

Authentication#

Please refer to Authentication.


Authorisation/Purchase Request (Payload)#

At the Point of Sale, if an existing Latitude Cardholder has selected payment method as Latitude interest free, the Sales Staff will tender the transaction using Latitude Interest free. The Point of Sale terminal will need to interact with Latitude’s Checkout API:

  1. API requests must be over HTTPS, any requests using HTTP will fail. Additionally, all requests will require the HTTP header Content-Type:application/json

  2. Ensure the HTTPS request contains the Authorization header

  3. Build the purchase request fields in the HTTPS POST body, refer to Purchase Specifications. The payload will contain
    a. merchant details
    b. optional: if home delivery, customer details
    c. order details
    d. platformType=instore-pos
    e. additional mandatory fields for instore integration: storeMid, terminalId, salesId
    f. for Mechants who have an agreement with Latitude for their orders or goods to be settled automatically (if the goods are taken by the Customer), "autoCapture" can be set to "full" or "partial". Latitude will automatically capture the order (or items) upon approval of the Customer's payment.

Note: Please contact your Latitude Financial Services representative to enable the auto capture feature

sample payload with Shipping Cost/home delivery

{
"merchantId": "directnetuser",
"storeMid": "123456789",
"terminalId": "T00101",
"salesId": "POS001",
"isTest": true,
"merchantReference": "102",
"amount": 850.00,
"currency": "AUD",
"customer": {
"firstName": "John",
"lastName": "Doe",
"phone": "0400000000",
"email": "john.doe@email.com"
},
"shippingAddress": {
"name": "John Doe",
"line1": "100 Spencer Street",
"line2": "",
"city": "Melbourne",
"postcode": "3000",
"state": "VIC",
"countryCode": "AU",
"phone": "0400000000"
},
"billingAddress": {
"name": "John Doe",
"line1": "100 Spencer Street",
"line2": "",
"city": "Melbourne",
"postcode": "3000",
"state": "VIC",
"countryCode": "AU",
"phone": "0400000000"
},
"orderLines": [
{
"name": "Echo Fit Compression Short",
"sku": "WSH07-28-Black",
"quantity": 5,
"unitPrice": 100.00,
"amount": 500.00,
"requiresShipping": true,
"isGiftCard": false
},
{
"name": "Short",
"sku": "ACW-24-Black",
"quantity": 2,
"unitPrice": 150.00,
"amount": 300.00,
"requiresShipping": true,
"isGiftCard": false
}
],
"totalShippingAmount": 50.00,
"platformType": "instore-pos",
"platformVersion": "0.0.1"
}

sample payload with only mandatory fields

{
"merchantId": "directnetuser",
"storeMid": "123456789",
"terminalId": "T00101",
"salesId": "POS001",
"isTest": true,
"merchantReference": "102",
"amount": 500.00,
"currency": "AUD",
"orderLines": [
{
"name": "Activewear Pants",
"quantity": 1,
"unitPrice": 200.00,
"amount": 200.00,
"requiresShipping": false,
"isGiftCard": false
},
{
"name": "Short",
"quantity": 2,
"unitPrice": 150.00,
"amount": 300.00,
"requiresShipping": false,
"isGiftCard": false
}
],
"platformType": "instore-pos"
}
  1. The POS will send the purchase request using HTTPS POST (server to server) to the Latitude Checkout API

  2. No promotionReference is required in the payload. The Latitude Checkout will handle promotion logic on behalf of the Merchant, and display the valid list of promotions for the Sales Staff to select (e.g., 6 months or 12 months).

  3. Latitude Checkout API will return a purchase response, refer to Purchase Specifications

  4. The POS will redirect the Sales Stafff to the redirectUrl as specified in the purchase response

  5. The Sales Staff will be shown a series of Latitude Checkout Merchant Order Summary forms

  6. The Latitude Checkout page will enable SMS support for the Sales Staff to initiate the SMS message to the Customer’s mobile.
    Alternatively, the Sales Staff can select “manual payment” to enter the Customer’s payment/card details and submit the payment

  7. Whilst the Customer is proceeding with payment on their mobile device, the POS can poll Latitude Checkout for the transaction status (use HTTPS GET (with Basic Authentication) to send the Status Request, or poll the statusUrl using HTTPS GET. The result field indicates the payment outcome.

Notes:

  • Save the gatewayReference and transactionReference against the transaction/order. These can be retrieved from the Status Response or statusUrl.
  • The gatewayReference is to be passed as a reference for the original transaction when performing voids, capture or refunds via Latitude APIs.
  • The merchantReference is used to search for the transaction in SMP Finding the transaction in SMP.
  1. Upon validation of the status response, the POS can display the appropriate message confirmation (or decline message) to the Sales Staff

  2. The Customer’s card/account number (masked) and Authorization Code will be returned to the Point of Sale once the payment is completed by the customer, which can then be used for printing on the Customers invoice

  3. If the Customer does not receive the SMS or could not complete the payment on their mobile device, the Sales Staff can select "Manual Payment" from the Latitude Checkout form (or the POS can invoke the manualPaymentUrl).

Auto Capture#

Latitude Checkout provides an auto capture feature that allows Merchants to immediately settle the Customer’s order.

Traditionally, a deferred settlement Merchant must initiate a subsequent ‘capture’ request after the order (authorisation) has taken place. The funds are then settled with the Merchant after the capture has been approved.

Note: For Settlement Method definitions, please refer to Terminology.

A new parameter in the Purchase Request called “autoCapture” (optional) will enable Latitude Checkout to initiate the capture request (after the authorisation has been approved) on behalf of deferred settlement Merchants.

autoCapture: full

autoCapture can be set to full to indicate that all goods are taken (now) by the Customer. All goods (orderLines) within the original authorisation will be settled. There is no need to include the goodsTaken parameter, as all orderLines will automatically be settled on behalf of the Merchant.

autoCapture: partial

autoCapture can be set to partial to indicate that only parts of the order are taken (now) by the Customer. Only these items will be settled. To indicate which orderLines are applicable, the orderLine must also contain goodsTaken:

  • goodsTaken: true to indicate that this orderLine is to be captured as part of the authorisation/purchase request
  • goodsTaken: false to indicate that this orderLine will not be captured. These remaining orderLines will need to be captured at a later date (refer to Order Management) so that the Merchant can be settled/paid.

autoCapture not present

If autoCapture is not present in the Purchase Request, Merchants can still opt to capture via Order Management (i.e Merchants can send the capture request at a later time).


Order Management#

Please refer to Order Management.