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
- for Merchants who are Deferred Settlement
Note: For Settlement Method definitions, please refer to Terminology.
Setup Pre-requisite Requirements#
| Merchant ID | Authorised 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 Secret | Authorised 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 URLs | The 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) Redirect URLS are both a HTTP GET Redirect. |
| 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)
| 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 verify requests (POST)
| Environment | Endpoint |
| Test/Sandbox | https://api.test.latitudefinancial.com/v1/applybuy-checkout-service/purchase/verify |
| Production | https://api.latitudefinancial.com/v1/applybuy-checkout-service/purchase/verify |
Integration Flow#
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
Merchant Backend initiates purchase by sending a Purchase Request with basic authentication. (See Endpoints and Authentication below) Latitude Checkout returns Purchase Response with redirectUrl
Merchant Backend notifies Merchant Frontend to initiate redirect
Merchant's Frontend to begin offsite checkout by redirecting customer to Latitude Checkout (redirectUrl returned in Purchase Response)
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:
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.
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
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:
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. customer details
c. order details
d. redirect URLs (complete and cancel)
sample payload with Shipping Cost
sample payload without Shipping Cost
The Merchant will send the purchase request using HTTPS POST (server to server) to the Latitude Checkout API
Latitude Checkout API will return a purchase response, refer to Purchase Specifications.
The Merchant will redirect the Customer to the redirectUrl as specified in the purchase response
The Customer will be shown a Latitude hosted payment page
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.
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
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.
Latitude Checkout API will return the verify response (refer to Verify Specifications) to show the result of the payment (completed, failed)
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 Merchant Portal.
The Customer’s Experience#
Customer views listing on merchant's website, adds item(s) to cart and proceeds to Merchant’s checkout page.
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
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)
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)
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
Order Management#
Please refer to Order Management