Skip to main content

Order Management

Introduction#

Latitude APIs provide a simple method for Merchant partners to securely integrate Interest Free payments from their eCommerce and instore platforms. Order Management via API integration can be used to submit the void, capture or refund.


Scope#

All order management APIs support the same payload format.

Latitude APIs cater for the following order management functions:

  • partial* and full Refunds (applicable to Instant and Deferred Settlement Merchant partners). Once refund integration to Latitude APIs are enabled, the Staff And Merchant Portal (SMP) will no longer be required to perform refunds. It is highly recommended to choose one method to process Refunds.
  • partial* and full Voids (applicable to Deferred Merchant partners). Once void integration to Latitude APIs are enabled, the Staff And Merchant Portal (SMP) will no longer be required to perform voids. It is highly recommended to choose one method to process voids.
  • partial* and full Captures (applicable to Deferred Merchant partners). Once capture integration to Latitude APIs are enabled, the Staff And Merchant Portal (SMP) will no longer be required to perform captures. It is highly recommended to choose one method to process captures.

Note: *Partial refers to when only a subset of items are to be actioned.
eg. a single purchase may contain 5 line items (orderLines), but only 2 line items (orderLines) are to be refunded in a single refund request. Multiple partial refunds for the same original purchase can occur as long as the total of all partial refunds does not exceed the original purchase.
A subset of the quantity within an orderLine is not supported.
Note: As of 1/8/2022, Merchants can send the Order Management amount to be any amount as required. OrderLines are now optional in all Order Management requests.


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. This will be the same Merchant ID as the Authorisation/Purchase.

If you have not received your Merchant ID or Merchant Secret please contact your Latitude Financial Services representative.
Notifications/webhook URL (Optional)Upon request, Latitude can configure an async request to be sent from Latitude’s server to the Merchant’s endpoint. If notifications have been set up for the Authorisation/Purchase, the same endpoint will automatically receive notifications for refunds/voids/captures. If you do not wish to receive notifications for all transaction types, please contact your Latitude Financial Services representative.

API Endpoints#

Latitude payment endpoints for refund requests (POST)

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

Latitude payment endpoints for void requests (POST)

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

Latitude payment endpoints for capture requests (POST)

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

Authentication#

Please refer to Authentication.


Refund Request#

Refunds can be used when the order has been settled (Merchant is instant settlement type OR Merchant is deferred settlement type and the order has been captured/settled).

For the payload format, refer to Order Management Specifications.

Latitude Checkout uses the information from the refund request (gatewayReference) to identify the original transaction (authorisation/purchase) that is to be refunded.

The same refund payload format can be used to perform partial refunds, or full refunds.

Multiple partial refunds can be performed, Latitude Checkout will validate that the sum of these individual partial refund requests are less than or equal to, the original authorisation/purchase amount.

Partial refunds If the authorisation/purchase contains multiple order lines (line items), Merchants can request a subset of the order lines to be refunded.

Full refunds If the authorisation/purchase contains multiple order lines (line items), Merchants can request all order lines to be refunded in a single refund request.

A subset of the quantity within an orderLine is not supported.

Note: As of 1/8/2022, Merchants can send the Refund amount to be any amount as required. OrderLines are now optional in all Order Management requests.

sample full refund request

{
"merchantId": "directnetuser",
"isTest": true,
"merchantReference": "9097775",
"gatewayReference": "906f5b69-255d-4f26-a81f-ca0d2c47fe35",
"amount": 320.00,
"currency": "AUD",
"type": "refund",
"description": "Customer change of mind",
"platformType": "direct"
}

sample partial refund request
Note: As of 1/8/2022, orderLines will be Optional

{
"merchantId": "directnetuser",
"isTest": true,
"merchantReference": "9097775",
"gatewayReference": "906f5b69-255d-4f26-a81f-ca0d2c47fe35",
"amount": 100.00,
"currency": "AUD",
"type": "refund",
"description": "Customer change of mind",
"platformType": "direct",
"orderLines": [
{
"name": "Echo Fit Compression Short",
"productUrl": "",
"sku": "WSH07-28-Black",
"quantity": 5,
"unitPrice": 20.00,
"amount": 100.00
}
]
}

sample refund responses

{
"merchantId": "directnetuser",
"merchantReference": "9097775",
"gatewayReference": "906f5b69-255d-4f26-a81f-ca0d2c47fe35",
"transactionReference": "pk0en4n9v5sg",
"promotionReference": "2018",
"amount": 320.00,
"currency": "AUD",
"type": "refund",
"result": "completed",
"platformType": "direct",
"error": ""
}
OR
{
"merchantId": "directnetuser",
"merchantReference": "9097775",
"gatewayReference": "906f5b69-255d-4f26-a81f-ca0d2c47fe35",
"transactionReference": "",
"promotionReference": "",
"amount": 320.00,
"currency": "AUD",
"type": "refund",
"result": "failed",
"platformType": "direct",
"error": "Could not find a matching purchase."
}

Void Request#

Voids can be used when the order has not been settled (Merchant is deferred settlement type).

For the payload format, refer to Order Management Specifications.

Latitude Checkout uses the information from the void request (gatewayReference) to identify the original transaction (authorisation/purchase) that is to be voided.

The same void payload format can be used to perform partial voids, or full voids.

Multiple partial voids can be performed, Latitude Checkout will validate that the sum of these individual partial void requests are less than or equal to, the original authorisation/purchase amount.

Partial voids If the authorisation/purchase contains multiple order lines (line items), Merchants can request a subset of the order lines to be voided.

Full voids If the authorisation/purchase contains multiple order lines (line items), Merchants can request all order lines to be voided in a single void request.

A subset of the quantity within an orderLine is not supported.

Note: As of 1/8/2022, Merchants can send the Void amount to be any amount as required. OrderLines are now optional in all Order Management requests.

sample full void request

{
"merchantId": "directnetuser",
"isTest": true,
"merchantReference": "9097775",
"gatewayReference": "906f5b69-255d-4f26-a81f-ca0d2c47fe36",
"amount": 320.00,
"currency": "AUD",
"type": "void",
"description": "Customer change of mind",
"platformType": "direct"
}

sample partial void request
Note: As of 1/8/2022, orderLines will be Optional

{
"merchantId": "directnetuser",
"isTest": true,
"merchantReference": "9097775",
"gatewayReference": "906f5b69-255d-4f26-a81f-ca0d2c47fe36",
"amount": 320.00,
"currency": "AUD",
"type": "void",
"description": "Customer change of mind",
"platformType": "direct",
"orderLines": [
{
"name": "Echo Fit Compression Short",
"productUrl": "",
"sku": "WSH07-28-Black",
"quantity": 5,
"unitPrice": 20.00,
"amount": 100.00
}
]
}

sample void responses

{
"merchantId": "directnetuser",
"merchantReference": "9097775",
"gatewayReference": "906f5b69-255d-4f26-a81f-ca0d2c47fe36",
"transactionReference": "pk0en4n9v5sg",
"promotionReference": "2018",
"amount": 320.00,
"currency": "AUD",
"type": "void",
"result": "completed",
"platformType": "direct",
"error": ""
}
OR
{
"merchantId": "directnetuser",
"merchantReference": "9097775",
"gatewayReference": "906f5b69-255d-4f26-a81f-ca0d2c47fe36",
"transactionReference": "",
"promotionReference": "",
"amount": 320.00,
"currency": "AUD",
"type": "void",
"result": "failed",
"platformType": "direct",
"error": "Could not find a matching purchase."
}

Capture Request#

Captures can be used when the Customer's order has been dispatched/delivered. The authorisation/order is ready for settlement (Merchant is deferred settlement type).

For the payload format, refer to Order Management Specifications.

Latitude Checkout uses the information from the capture request (gatewayReference) to identify the original transaction (authorisation/purchase) that is to be captured.

The same refund payload format can be used to perform partial captures, or full captures.

Multiple partial captures can be performed, Latitude Checkout will validate that the sum of these individual partial capture requests are less than or equal to, the original authorisation/purchase amount.

Partial captures If the authorisation/purchase contains multiple order lines (line items), Merchants can request a subset of the order lines to be captured.

Full captures If the authorisation/purchase contains multiple order lines (line items), Merchants can request all order lines to be captured in a single capture request.

A subset of the quantity within an orderLine is not supported.

Note: As of 1/8/2022, Merchants can send the Capture amount to be any amount as required. OrderLines are now optional in all Order Management requests.

sample full capture request

{
"merchantId": "directnetuser",
"isTest": true,
"merchantReference": "9097775",
"gatewayReference": "906f5b69-255d-4f26-a81f-ca0d2c47fe37",
"amount": 320.00,
"currency": "AUD",
"type": "capture",
"description": "Customer order dispatched",
"platformType": "direct"
}

sample partial capture request
Note: As of 1/8/2022, orderLines will be Optional

{
"merchantId": "directnetuser",
"isTest": true,
"merchantReference": "9097775",
"gatewayReference": "906f5b69-255d-4f26-a81f-ca0d2c47fe37",
"amount": 320.00,
"currency": "AUD",
"type": "capture",
"description": "Customer order dispatched",
"platformType": "direct",
"orderLines": [
{
"name": "Echo Fit Compression Short",
"productUrl": "",
"sku": "WSH07-28-Black",
"quantity": 5,
"unitPrice": 20.00,
"amount": 100.00
}
]
}

sample capture responses

{
"merchantId": "directnetuser",
"merchantReference": "9097775",
"gatewayReference": "906f5b69-255d-4f26-a81f-ca0d2c47fe37",
"transactionReference": "pk0en4n9v5sg",
"promotionReference": "2018",
"amount": 320.00,
"currency": "AUD",
"type": "capture",
"result": "completed",
"platformType": "direct",
"error": ""
}
OR
{
"merchantId": "directnetuser",
"merchantReference": "9097775",
"gatewayReference": "906f5b69-255d-4f26-a81f-ca0d2c47fe37",
"transactionReference": "",
"promotionReference": "",
"amount": 320.00,
"currency": "AUD",
"type": "capture",
"result": "failed",
"platformType": "direct",
"error": "Could not find a matching purchase."
}