Skip to main content

Direct Integration for Custom eCommerce Platforms

Introduction#

Latitude APIs provide a simple method for Merchant partners to securely integrate Interest Free payments from their eCommerce platforms. The Payment APIs leverage Latitude’s PCI-compliant hosted payment page to enable Customer payments from web-based platforms and mobile devices.


Scope#

The release of this document will provide details on:

  • integrations for eCommerce Platforms
  • for Merchants who are Instant Settlement
    * accepting the payment (purchase)
    * accepting the partial/full refund
  • for Merchants who are Deferred Settlement
    * accepting the payment (authorisation)
    * order management requests for partial/full refund, partial/full void and partial/full capture

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


Setup Pre-requisite Requirements#

Merchant IDAuthorised Merchants are identified by a unique Merchant ID which must be included in all request messages.

If you have not received your Merchant ID or Merchant Secret please contact your Latitude Financial Services representative.
Merchant SecretAuthorised Merchants use the Merchant Secret for basic authentication in all request messages.

If you have not received your Merchant ID or Merchant Secret please contact your Latitude Financial Services representative.
Redirect URLsThe purchase request payload can support dynamic URLs for redirecting the Customer when the purchase has been completed (transaction is approved or declined), or if the Customer selects to cancel from the hosted payment form.
complete for approved or declined or failed transactions
cancel for cancelled transactions (Customer decides to return to cart)
Notifications/webhook URL (Optional)Upon request, Latitude can configure an async request to be sent from Latitude’s server to the Merchant’s endpoint

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 verify requests (POST)

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

Integration Flow#

Latitude portal image

  1. Merchant Frontend sends customer and cart info to their backend. Typically happens when Customer adds item(s) to cart, proceeds to checkout page and selects Latitude Interest free on checkout page

  2. Merchant Backend initiates purchase by sending a Purchase Request with basic authentication. (See Endpoints and Authentication below) Latitude Checkout returns Purchase Response with redirectUrl

  3. Merchant Backend notifies Merchant Frontend to initiate redirect

  4. Merchant's Frontend to begin offsite checkout by redirecting customer to Latitude Checkout (redirectUrl returned in Purchase Response)

  5. Customer is redirected to Merchant Frontend after Customer completes the purchase on Latitude Checkout by entering payment details. (complete URL sent by merchant in Purchase Request)

    Example of the complete URL, used to redirect after payment is completed:

    complete_URL/?gatewayReference=0l2vn4lmdsg0&merchantReference=1025&transactionReference=9553ecf2-0a62-494c-86f3-dc23b8422722
  6. Merchant Frontend hands over verification to Merchant Backend.

    Note: This is recommended for better UX as merchant can show feedback to customer at this point. Alternatively Merchant can skip this step and go to step 7.

    This redirect includes merchantReference, transactionReference and gatewayReference in query-string which is required for step 7.
  7. Merchant Backend verifies payment by sending a Verify Request to Latitude Checkout with basic authentication. (See Endpoints and Authentication below) Latitude Checkout returns Verify Response

  8. Merchant shows order confirmation or decline feedback based on response sent by Latitude Checkout in step 7 above


Authentication#

Please refer to Authentication.


Authorisation/Purchase Request (Payload)#

When a Customer has performed checkout from the Merchant’s site, and selects the option to pay using Latitude Interest free, the Merchant 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. customer details
    c. order details
    d. redirect URLs (complete and cancel)

sample payload with Shipping Cost

{
"merchantId": "directnetuser",
"isTest": true,
"merchantReference": "102",
"amount": 850.00,
"currency": "AUD",
"customer": {
"firstName": "John",
"lastName": "Doe",
"phone": "+61400000000",
"email": "john.doe@email.com"
},
"shippingAddress": {
"name": "John Doe",
"line1": "100 Spencer Street",
"line2": "",
"city": "Melbourne",
"postcode": "3000",
"state": "VIC",
"countryCode": "AU",
"phone": "+61400000000"
},
"billingAddress": {
"name": "John Doe",
"line1": "100 Spencer Street",
"line2": "",
"city": "Melbourne",
"postcode": "3000",
"state": "VIC",
"countryCode": "AU",
"phone": "+61400000000"
},
"orderLines": [
{
"name": "Echo Fit Compression Short",
"productUrl": "",
"sku": "WSH07-28-Black",
"quantity": 5,
"unitPrice": 100.00,
"amount": 500.00,
"requiresShipping": true,
"isGiftCard": false
},
{
"name": "Short",
"productUrl": "",
"sku": "ACW-24-Black",
"quantity": 2,
"unitPrice": 150.00,
"amount": 300.00,
"requiresShipping": true,
"isGiftCard": false
}
],
"merchantUrls": {
"cancel": "https://store1.lmerchant.com/purchase/checkout",
"complete": "https://store1.lmerchant.com/purchase/complete"
},
"totalShippingAmount": 50.00,
"platformType": "direct",
"platformVersion": "0.0.1"
}

sample payload without Shipping Cost

{
"merchantId": "directnetuser",
"isTest": true,
"merchantReference": "102",
"amount": 500.00,
"currency": "AUD",
"customer": {
"firstName": "John",
"lastName": "Doe",
"phone": "+61400000000",
"email": "john.doe@email.com"
},
"shippingAddress": {
"name": "John Doe",
"line1": "100 Spencer Street",
"line2": "",
"city": "Melbourne",
"postcode": "3000",
"state": "VIC",
"countryCode": "AU",
"phone": "+61400000000"
},
"billingAddress": {
"name": "John Doe",
"line1": "100 Spencer Street",
"line2": "",
"city": "Melbourne",
"postcode": "3000",
"state": "VIC",
"countryCode": "AU",
"phone": "+61400000000"
},
"orderLines": [
{
"name": "Echo Fit Compression Short",
"productUrl": "",
"sku": "WSH07-28-Black",
"quantity": 1,
"unitPrice": 200.00,
"amount": 200.00,
"requiresShipping": false,
"isGiftCard": false
},
{
"name": "Short",
"productUrl": "",
"sku": "ACW-24-Black",
"quantity": 2,
"unitPrice": 150.00,
"amount": 300.00,
"requiresShipping": false,
"isGiftCard": false
}
],
"merchantUrls": {
"cancel": "https://store1.lmerchant.com/purchase/checkout",
"complete": "https://store1.lmerchant.com/purchase/complete"
},
"platformType": "direct",
"platformVersion": "0.0.1"
}
  1. The Merchant will send the purchase request using HTTPS POST (server to server) to the Latitude Checkout API

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

  3. The Merchant will redirect the Customer to the redirectUrl as specified in the purchase response

  4. The Customer will be shown a Latitude hosted payment page

Latitude portal image

  1. No promotionReference is required from the Merchant. The Latitude Checkout will handle promotion logic on behalf of the Merchant, and display the valid list of promotions for the Customer to select (e.g., 6 months or 12 months). The Customer can then enter their payment/card details and submit the payment.

  2. Once the payment has been processed, Latitude Checkout will redirect the Customer according to the Merchant’s “complete” endpoint that was passed in the purchase request. The url will be appended with Latitude’s custom fields: merchantReference, transactionReference, gatewayReference:

    complete_URL/?merchantReference=xxxxx&transactionReference=yyyyy&gatewayReference=zzzzz

    example:
    https://store1.lmerchant.com/payment/complete/?merchantReference=xxxxx&transactionReference=yyyyy&gatewayReference=zzzzz
  3. The Merchant receives the redirect (refer to Redirect Specifications), and builds the verify request message (refer to Verify Specifications). The request is sent to Latitude Checkout API using the POST method with basic authentication.

Note: Verify Request must be sent within an hour of creating the purchase request to avoid timeout errors.

  1. Latitude Checkout API will return the verify response (refer to Verify Specifications) to show the result of the payment (completed, failed)

  2. Upon validation of the verify response, the Merchant can show the order confirmation (or order decline) to the Customer

Notes:

  • Save the gatewayReference and transactionReference against the transaction/order. These can be retrieved from the ‘redirect from Latitude Checkout’ OR the ‘Verify 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 (refer to section Finding the transaction in SMP.

The Customer’s Experience#

  1. Customer views listing on merchant's website, adds item(s) to cart and proceeds to Merchant’s checkout page.

  2. Customer selects Latitude Interest free and clicks on Pay now.
    a. Merchant initiates purchase by sending a POST request (purchase request) to the Latitude Checkout API
    b. Latitude Checkout API will return purchase response containing a redirectUrl

    Latitude portal image

  3. The Merchant will redirect the Customer to Latitude’s hosted Checkout page (redirectUrl). On Latitude’s hosted Checkout page, the Customer selects promotion (eg. 6 months or 12 months)

    Latitude portal image

  4. Existing Latitude cardholders can select to pay with card or account number. New cardholders, who have recently applied successfully for a Latitude card product but have not received their card yet, can select to pay with their account number (new Customers would have received an email which details their account number)

  5. Upon payment completion, the Latitude Checkout will redirect the Customer back to the Merchant’s site. The Merchant verifies the payment status/outcome and shows the order confirmation to the Customer

Latitude portal image


Order Management#

Please refer to Order Management