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. Latitude supports 2 methods:

  1. 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
  2. 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
    * 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

Latitude payment endpoints for cancel requests (POST)

EnvironmentEndpoint
Test/Sandboxhttps://api.test.latitudefinancial.com/v1/applybuy-checkout-service/cancel
Productionhttps://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.

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

Latitude Manual Payment Session will time out after 20 minutes

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

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": "123456789", **merchantId will always be the same as storeMid for POS-Direct**
"storeMid": "123456789",
"terminalId": "T00101",
"salesId": "POS001",
"isTest": true,
"merchantReference": "102",
"amount": 850.00,
"currency": "AUD", **update this field to reflect the correct currency**
"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": "123456789", **merchantId will always be the same as storeMid for POS-Direct**
"storeMid": "123456789",
"terminalId": "T00101",
"salesId": "POS001",
"isTest": true,
"merchantReference": "102",
"amount": 500.00,
"currency": "AUD", **update this field to reflect the correct currency**
"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 Staff 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 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.
  1. Upon validation of the status response, the POS can display the appropriate message confirmation (or decline message) to the Sales Staff

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

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

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

{
"merchantId": "123456789", **merchantId will always be the same as storeMid for Instore-Direct**
"storeMid": "123456789",
"terminalId": "T00101",
"salesId": "POS001",
"isTest": true,
"merchantReference": "102",
"promotionReference":"2012",
"amount": 850.00,
"currency": "AUD", **update this field to reflect the correct currency**
"customer": {
"firstName": "John",
"lastName": "Doe",
"phone": "+61400000000",
"email": "john.doe@email.com"
},
"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-direct",
"platformVersion": "0.0.1"
}

sample payload with only mandatory fields (orderLines not required)

{
"merchantId": "123456789", **merchantId will always be the same as storeMid for Instore-Direct**
"storeMid": "123456789",
"terminalId": "T00101",
"salesId": "POS001",
"isTest": true,
"merchantReference": "102",
"promotionReference":"2012",
"amount": 500.00,
"currency": "AUD", **update this field to reflect the correct currency**
"customer": {
"firstName": "John",
"lastName": "Doe",
"phone": "+61400000000",
"email": "john.doe@email.com"
},
"platformType": "instore-direct"
}
  1. The POS will send the purchase request using HTTPS POST (server to server) to the Latitude Checkout API

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

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

  4. Customers will receive an SMS message on their mobile, containing a payment link.

  5. 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.
  1. Upon validation of the status response, the POS can display the appropriate message confirmation (or decline message) to the Sales Staff

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

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