This topic explains how to configure [Latitude](https://www.latitudefinancial.com.au/interest-free/) as a third-party buy-now-pay-later (BNPL) payment provider in StoreConnect.

Latitude is an Australian and New Zealand retail finance product. At checkout the customer chooses a Latitude payment plan (for example "10 months interest free"), then completes the application and payment on Latitude's hosted page. StoreConnect supports Latitude on both web storefronts and POS.

:::note
Latitude in StoreConnect uses Latitude's **Apply & Buy / Interest Free** retail finance API (`applybuy-checkout-service`). This is different from Latitude's consumer "Click to Pay" wallet for existing cardholders, which is not what this integration provides.
:::

You can use Latitude for:

- Standard checkout (web and POS)
- Additional and Salesforce payments
- Pre-authorization
- Refunds
- Payment plans

To process transactions using Latitude:

- Customers must have an Australian or New Zealand mobile number (for the POS SMS payment link)
- A minimum purchase of **$250 AUD** applies per Latitude transaction

## What you need

- A Latitude merchant account enabled for Apply & Buy / Interest Free
- **Merchant ID** and **Merchant Secret** issued by Latitude
- For POS: per-outlet Latitude credentials and Latitude **terminal IDs** for each outlet or register that will take Latitude payments

## Get credentials from Latitude

- A **Merchant ID** (entered as the StoreConnect **API Key**)
- A **Merchant Secret** (entered as the StoreConnect **API Secret**)
- One or more **terminal IDs** for POS use, one per outlet or register
- Optionally, separate Merchant ID / Secret pairs per outlet for POS

Sandbox credentials are issued separately from production credentials. Request both from your Latitude contact.

## Configure Latitude in StoreConnect

### Basic configuration

1. Open StoreConnect and go to **Settings > Payments > Payment providers**.
2. Select **New**. Complete the fields as follows, then **Save**:

| StoreConnect field | Select or enter                                  |
|--------------------|--------------------------------------------------|
| Name               | Latitude                                         |
| Provider           | Select **Latitude** from the list                |
| API Mode           | `sandbox` for testing or `production` for live   |
| API Key            | Merchant ID supplied by Latitude                 |
| API Secret         | Merchant Secret supplied by Latitude             |
| Channels           | `pos;web`, `pos`, or `web` depending on use      |
| Active             | Tick to enable the provider                      |

### API modes

- `sandbox` — routes to Latitude's test environment (`api.test.latitudefinancial.com`). Use with sandbox credentials.
- `production` — routes to Latitude's live environment (`api.latitudefinancial.com`).

### API options

Additional configuration is set via the **API Options** field as YAML key/value pairs.

| Option | Type | Description |
|--------|------|-------------|
| `pos_enabled` | Boolean | Set to `true` to make Latitude available in the POS checkout |
| `pos_store_mid` | String | Optional store-level Merchant ID for POS. Defaults to **API Key** when not set |
| `pos_outlet_api_keys` | Hash | Per-outlet POS credentials, keyed by outlet SFID. Each value is `{api_key, api_secret}`. Required for any outlet that takes Latitude POS payments |
| `terminal_ids` | Hash | Maps outlet or register SFIDs to Latitude terminal IDs. Register-level entries take precedence over outlet-level entries |
| `use_preauth` | Boolean | When `true`, Latitude payments are preauthorized and captured (or released) separately. Defaults to `false` (immediate full capture) |
| `customer_required` | Boolean | When `true`, the POS requires a named customer on the cart before Latitude can be used. Defaults to `false` |
| `ineligible_product_types` | Array | Item types that cannot be paid for with Latitude (see below) |
| `ineligible_product_ids` | Array | Specific product SFIDs that cannot be paid for with Latitude |

#### Example API options

```yaml
pos_enabled: true
use_preauth: false
customer_required: false
ineligible_product_types:
  - virtual
  - voucher
ineligible_product_ids:
  - a0FXx000000AbCdEFG
terminal_ids:
  OUTLET_SFID: TERM001
  REGISTER_SFID: TERM002
pos_outlet_api_keys:
  OUTLET_SFID:
    api_key: merchant-id-for-this-outlet
    api_secret: merchant-secret-for-this-outlet
```

### Product eligibility

Some item types are not appropriate for retail finance and should be excluded from Latitude. Set `ineligible_product_types` to any combination of:

| Value | Excludes |
|-------|----------|
| `virtual` | Non-physical products (digital goods, services) |
| `voucher` | Voucher and gift card products |
| `shipping` | Shipping line items |
| `promo` | Promotional discount line items |
| `tipping` | Tip line items |
| `surcharge` | Payment surcharge line items |
| `cash_rounding` | Cash rounding adjustments |

When a cart contains both eligible and ineligible items, the Latitude payment is capped at the eligible portion and the remainder must be split-paid using another method. When the entire cart is ineligible, Latitude shows a banner explaining nothing is eligible and the payment button is disabled.

## Web checkout flow

1. The customer selects **Latitude** at checkout.
2. StoreConnect creates a Latitude purchase session and redirects the customer to Latitude's hosted page.
3. The customer applies for finance or signs in to their existing Latitude account, chooses a payment plan and completes the purchase.
4. Latitude redirects the customer back to StoreConnect and the order is finalized.

Additional payments against an existing order (for example, settling a balance) are supported and reuse the same flow.

## POS checkout flow

1. The POS operator selects **Latitude** from the payment methods.
2. Available payment plans (interest-free promotions) load automatically from Latitude.
3. The operator selects a plan and enters the customer's mobile number.
4. Tapping **Send payment link** triggers Latitude to SMS the customer a payment link.
5. The POS displays a QR code, a **Desktop Payment** button, and a status message. The POS polls every 3 seconds.
6. The customer completes the payment on their device. The POS auto-completes the order on success.
7. The customer has 20 minutes to complete the payment before it expires. A **Cancel transaction** button is available at any time.

:::note
Latitude in POS is automatically disabled when the register is offline and re-enabled when connectivity is restored.
:::

### POS prerequisites

- The POS must be online.
- The cart total must be at or above the selected plan's minimum (and not above its maximum).
- The customer must have a valid Australian or New Zealand mobile number.
- A `terminal_ids` entry must exist for either the register or its outlet.
- If `customer_required: true`, a named customer must be on the cart before Latitude can be used.

## Refunds

Latitude supports both full and partial refunds from StoreConnect.

- **Captured payments** call Latitude's refund API against the original transaction.
- **Preauthorized (uncaptured) payments** call Latitude's void API to release or reduce the hold. A full refund releases the preauthorization entirely; a partial refund reduces the held amount.

Refunds are protected against duplicate submission — repeating a refund with the same reference and amount returns a `409 Conflict` from StoreConnect.

## Preauthorization

When `use_preauth: true`, Latitude payments are authorised but not captured. Funds are held on the customer's Latitude account until you capture or release the payment from the order in StoreConnect. Partial captures and partial releases are supported.

When `use_preauth: false` (the default), payments are captured in full at the time of purchase.

## Payment plans

Latitude offers a range of interest-free payment plans (for example, "6 months interest free", "10 months interest free"). Plans have minimum and maximum purchase amounts:

- If the order total is below a plan's minimum, the operator (or customer) sees a warning.
- If the order total is above a plan's maximum, the operator (or customer) sees a warning.
- On POS, the first available plan is pre-selected by default.

The set of available plans is configured by Latitude on the merchant account, not in StoreConnect.

## Testing in sandbox

After setting **API Mode** to `sandbox` and entering sandbox credentials, you can test web and POS flows using Latitude's sandbox test card:

| Field       | Value              |
|-------------|--------------------|
| Card Number | `4377320005654057` |
| Expiry      | `07/29`            |
| CVV         | `631`              |

## Troubleshooting

- **"Environment not valid for Payment Provider"** — the **API Mode** does not match the credentials. Switch to `sandbox` if using sandbox credentials, or `production` if using live credentials.
- **POS shows Latitude as disabled** — the register is offline, or `pos_enabled` is not set to `true` in **API Options**, or there is no `terminal_ids` mapping for the register or its outlet.
- **"A customer is required for Latitude payments"** — `customer_required: true` is set; add a named customer to the cart before selecting Latitude.
- **"Amount below minimum" / "Amount exceeds maximum"** — the cart total is outside the selected plan's range. Choose a different plan or adjust the cart.
- **Invalid phone number** — the POS requires a valid Australian or New Zealand mobile number.
- **Payment timeout** — the customer has 20 minutes to complete the SMS payment link.