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. Latitude supports 2 methods:
- Merchants can leverage a series of Latitude-hosted UX-designed screens, which provide visuals of the Order Summary to the Sales Staff (use platformType=instore-pos); OR
- Merchants can host their own POS UX screens, and only use Latitude APIs to post and retrieve transaction information (use platformType=instore-direct).
In both integrations types, 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
Note: the platformType parameter is used to determine the integration type. If you are unsure of the integration type for your platform, please contact your Latitude Financial Services representative
Scope#
The release of this document will provide details on:
- integrations for instore Point of Sale
- for Merchants who are Instant Settlement
- for Merchants who are Deferred Settlement
- auto capture features
Note: For Settlement Method definitions, please refer to Terminology.
Setup Pre-requisite Requirements#
| Merchant ID | Authorised 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 Secret | Authorised 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)
| Environment | Endpoint |
| Test/Sandbox | https://api.test.latitudefinancial.com/v1/applybuy-checkout-service/purchase |
| Production | https://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)
| Environment | Endpoint |
| Test/Sandbox | https://api.test.latitudefinancial.com/v1/applybuy-checkout-service/purchase/{gatewayReference}/status |
| Production | https://api.latitudefinancial.com/v1/applybuy-checkout-service/purchase/{gatewayReference}/status |
Latitude payment endpoints for cancel requests (POST)
| Environment | Endpoint |
| Test/Sandbox | https://api.test.latitudefinancial.com/v1/applybuy-checkout-service/cancel |
| Production | https://api.latitudefinancial.com/v1/applybuy-checkout-service/cancel |
Authentication#
Please refer to Authentication.
Type 1 Integration Flow - instore-pos#
In the following flow, Latitude-hosted screens (as seen in steps 3 - 10) are enabled when platformType=instore-pos.
| Step | Detail | Example Screens |
| 1 | The Sales Staff interfaces with the POS screens. The Sales Staff will tender the sale with Latitude Interest Free as the payment option |  |
| 2 | The POS sends Purchase Request to Latitude’s API endpoint (note: platformType=instore-pos) | |
| 3 | The 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 25 minutes Note: "result": "submitted" |  |
| 4 | Once 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 25 minutes Note: "result": "submitted" |  |
| 5 | Whilst 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. poll using the statusUrl that has been returned in Purchase Response b. integrate with Latitude API to send the Status Request Notes: - "result": "initiated" indicates that the customer has clicked the payment link and the payment page is loaded - Timeout will occur after 20mins on click of the SMS link |  |
| 6 | Once 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 |  |
| 7 | The POS will notify the Sales Staff with an appropriate message/prompt (and the order is updated) on the POS | |
| 8 | If 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" |  |
| 9 | Manual payment will display the Latitude payment form. Sales Staff can enter the Customer’s card/account details and submit the payment Latitude Manual Payment Session will time out after 20 minutes Note: "result": "initiated" |  |
| 10 | When 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 |  |
| 11 | Recommendations | - 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 |
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:
API requests must be over HTTPS, any requests using HTTP will fail. Additionally, all requests will require the HTTP header Content-Type:application/json
Ensure the HTTPS request contains the Authorization header
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
sample payload with only mandatory fields
The POS will send the purchase request using HTTPS POST (server to server) to the Latitude Checkout API
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).
Latitude Checkout API will return a purchase response, refer to Purchase Specifications
The POS will redirect the Sales Staff to the redirectUrl as specified in the purchase response
The Sales Staff will be shown a series of Latitude Checkout Merchant Order Summary forms
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 paymentWhilst the Customer is proceeding with payment on their mobile device, the POS can poll Latitude Checkout for the transaction status via 2 available methods:
a. poll using the statusUrl that has been returned in Purchase Response
b. integrate with Latitude API to send the Status Request
The result field indicates the payment outcome.
c. Timeout will occur after 20mins on every click of the SMS Link.
Notes:
- Save the gatewayReference and transactionReference against the transaction/order. These can be retrieved from the statusUrl or Status Response.
- 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 Merchant Portal.
Upon validation of the status response, the POS can display the appropriate message confirmation (or decline message) to the Sales Staff
The status response will contain Customer’s card/account number (masked) and Authorization Code, which can then be used for printing on the Customer's invoice
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). Customers will need to provide their payment details to the Sales Staff to input into the payment screen.
Type 2 Integration Flow instore-direct#
When platformType=instore-direct, all POS screens will be designed and hosted by the Merchant.
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:
API requests must be over HTTPS, any requests using HTTP will fail. Additionally, all requests will require the HTTP header Content-Type:application/json
Ensure the HTTPS request contains the Authorization header
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. the applicable interest free promotion (send the promotion code in field:promotionReference)
e. platformType=instore-direct
f. additional mandatory fields for instore integration: storeMid, terminalId, salesId
g. 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 orderLines (optional)
sample payload with only mandatory fields (orderLines not required)
The POS will send the purchase request using HTTPS POST (server to server) to the Latitude Checkout API
promotionReference is required in the payload. Merchants will need to indicate the promotion code to be applied to the sale. If you are unsure of the valid promotion codes, please contact your Latitude Financial Services representative
Latitude Checkout API will return a purchase response, refer to Purchase Specifications
Customers will receive an SMS message on their mobile, containing a payment link.
Whilst the Customer is proceeding with payment on their mobile device, the POS can poll Latitude Checkout for the transaction status via 2 available methods:
a. poll using the statusUrl that has been returned in Purchase Response
b. integrate with Latitude API to send the Status Request
The result field indicates the payment outcome.
c. Timeout will occur after 20mins on every click of the SMS Link.
Notes:
- Save the gatewayReference and transactionReference against the transaction/order. These can be retrieved from the statusUrl or Status Response.
- 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 Merchant Portal.
Upon validation of the status response, the POS can display the appropriate message confirmation (or decline message) to the Sales Staff
The status response will contain Customer’s card/account number (masked) and Authorization Code, which can then be used for printing on the Customer's invoice
If the Customer does not receive the SMS or could not complete the payment on their mobile device, Merchants can invoke a Latitude-hosted payment screen by using the manualPaymentUrl (returned in Purchase Response). Customers will need to provide their payment details to the Sales Staff to input into the payment screen.
Cancel#
Applicable only for Instore Integration
In instances when customer decides not to proceed with the purchase and the payment link has already been sent, the POS can provide option to cancel the transaction. Instore-POS can trigger a cancel request only for transactions in status "initiated" or "submitted".
Auto Capture#
Applies to all integration types.
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#
Applies to all integration types.
Please refer to Order Management.