> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Latitude / Gem

> Connect to Latitude or Gem to accept buy now, pay later payments in Australia and New Zealand.

Latitude and Gem are buy now, pay later (BNPL) payment providers by Latitude Financial. Latitude operates in Australia and Gem operates in New Zealand. Both use a redirect flow where the buyer approves the payment on a hosted page.

Each provider has two connector variants:

| Provider      | Instant Settlement  | Deferred Settlement   |
| ------------- | ------------------- | --------------------- |
| Latitude (AU) | `latitude-latitude` | `latitude-latitudeds` |
| Gem (NZ)      | `gem-gem`           | `gem-gemds`           |

* **Instant Settlement** - Funds are captured immediately during the transaction.
* **Deferred Settlement** - Funds are authorized first and captured manually later.

## Setup

Contact the Latitude [merchant support](https://resources.latitudefinancial.com/docs/interest-free/operations/merchant-support) team to obtain credentials.

## Credentials

When setting up Latitude in the dashboard, configure the following credentials:

* **Merchant ID** - The merchant ID obtained from the Latitude Merchant Integration Support team.
* **Merchant Secret** - The merchant secret obtained from the Latitude Merchant Integration Support team.

## Features

Both connectors support the following features:

* **Partial refunds** - Refund a portion of the captured amount
* **Refunds** - Refund transactions in full
* **Transaction sync** - Automatic synchronization of transaction status updates

The **Deferred Settlement** connector additionally supports:

* **Delayed capture** - Authorize a payment and capture it at a later time
* **Partial capture** - Capture a portion of the authorized amount
* **Void** - Cancel an authorized transaction before capture

## Supported countries

| Country code | Provider |
| ------------ | -------- |
| `AU`         | Latitude |
| `NZ`         | Gem      |

## Supported currencies

| Currency code | Provider |
| ------------- | -------- |
| `AUD`         | Latitude |
| `NZD`         | Gem      |

## Limitations

The following features are not supported by this connector:

* **Over capture** - Capturing more than the authorized amount is not supported
* **Partial authorization** - Accepting a partial amount is not supported
* **Payment method tokenization** - Storing payment methods for future use is not supported
* **Zero auth** - Zero-dollar verification transactions are not supported
* **Settlement reporting** - Automatic settlement reporting is not supported

Additional limitations:

* **Cart items required** - Cart items must be included with every transaction.
* **Transaction refresh** - Only transactions with a `buyer_approval_pending` status can be refreshed through the dashboard. Instant Settlement transactions update to `capture_succeeded`, while Deferred Settlement transactions update to `authorization_succeeded`.

## Required fields

Latitude requires the following buyer information with every transaction:

* First name
* Last name
* Address line 1
* City
* Postal code
* Country

## Integration

The default integration for Latitude uses a redirect to a hosted payments page.

Start by creating a new transaction with the following required fields. Use `latitude` or `gem` as the method for Instant Settlement, or `latitudeds` or `gemds` for Deferred Settlement.

<CodeGroup>
  ```csharp C# theme={"system"}
  var transaction = await client.Transactions.CreateAsync(
    transactionCreate: new TransactionCreate()
    {
      Amount = 1299,
      Currency = "AUD",
      Country = "AU",
      PaymentMethod =
        TransactionCreatePaymentMethod.CreateCheckoutSessionWithUrlPaymentMethodCreate(
          new RedirectPaymentMethodCreate()
          {
            Method = "latitude",
            RedirectUrl = "https://example.com/callback",
          }
        ),
    }
  );
  ```

  ```go Go theme={"system"}
  amount := int64(1299)
  currency := "AUD"
  country := "AU"
  method := "latitude"
  redirectUrl := "https://example.com/callback"

  redirectPaymentMethodCreate := components.RedirectPaymentMethodCreate{
    Method: method,
    RedirectUrl: redirectUrl,
  }
  paymentMethod := components.CreateTransactionCreatePaymentMethodRedirectPaymentMethodCreate(redirectPaymentMethodCreate)

  transactionCreate := components.TransactionCreate{
    Amount:        amount,
    Currency:      currency,
    Country:       &country,
    PaymentMethod: &paymentMethod,
  }

  transaction, err := client.Transactions.Create(ctx, transactionCreate, nil, nil)
  ```

  ```java Java theme={"system"}
  CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
    .transactionCreate(TransactionCreate.builder()
      .amount(1299L)
      .currency("AUD")
      .country("AU")
      .paymentMethod(TransactionCreatePaymentMethod.of(RedirectPaymentMethodCreate.builder()
        .method("latitude")
        .redirectUrl("https://example.com/callback")
        .build()))
      .build())
    .call();

  Transaction transaction = transactionResponse.transaction().orElse(null);
  ```

  ```php PHP theme={"system"}
  $transactionCreate = new TransactionCreate(
    amount: 1299,
    currency: 'AUD',
    country: 'AU',
    paymentMethod: new RedirectPaymentMethodCreate(
      method: 'latitude',
      redirectUrl: 'https://example.com/callback'
    )
  );
  $response = $client->transactions->create($transactionCreate);
  $transaction = $response->transaction;
  ```

  ```python Python theme={"system"}
  transaction: models.Transaction = client.transactions.create(
    amount=1299,
    currency="AUD",
    country="AU",
    payment_method={
      "method": "latitude",
      "redirect_url": "https://example.com/callback",
    }
  )
  ```

  ```ts TypeScript theme={"system"}
  const transaction = await client.transactions.create({
    amount: 1299,
    currency: "AUD",
    country: "AU",
    paymentMethod: {
      method: "latitude",
      redirectUrl: "https://example.com/callback",
    },
  });
  ```
</CodeGroup>

After the transaction is created, the API response includes a `payment_method.approval_url` and the status is set to `buyer_approval_pending`. The approval URL expires after 30 minutes.

```json theme={"system"}
{
  "type": "transaction",
  "id": "ea1efdd0-20f9-44d9-9b0b-0a3d71e9b625",
  "payment_method": {
    "type": "payment-method",
    "approval_url": "https://cdn.gr4vy.com/connectors/..."
  },
  "method": "latitude"
}
```

Redirect the buyer to the `approval_url` (open in a browser or Webview), where they can complete the payment. Once the buyer approves, the transaction progresses to a `capture_succeeded` (Instant Settlement) or `authorization_succeeded` (Deferred Settlement) state.

## Connection options

The Latitude connector supports passing a promotion reference when creating a transaction. See the Latitude [purchase request API](https://resources.latitudefinancial.com/docs/interest-free/integration-guides/apis/api-specifications-purchase/) for details.

<CodeGroup>
  ```csharp C# highlight={6-12} theme={"system"}
  var transaction = await client.Transactions.CreateAsync(
    transactionCreate: new TransactionCreate()
    {
      Amount = 1299,
      Currency = "AUD",
      ConnectionOptions = new TransactionCreateConnectionOptions()
      {
        LatitudeLatitude = new ConnectionOptionsLatitudeLatitude()
        {
          PromotionReference = "2012",
        },
      },
      PaymentMethod =
        TransactionCreatePaymentMethod.CreateCheckoutSessionWithUrlPaymentMethodCreate(
          new RedirectPaymentMethodCreate()
          {
            Method = "latitude",
            RedirectUrl = "https://example.com/callback",
          }
        ),
    }
  );
  ```

  ```go Go highlight={1-5,12} theme={"system"}
  connectionOptions := components.TransactionCreateConnectionOptions{
    LatitudeLatitude: &components.ConnectionOptionsLatitudeLatitude{
      PromotionReference: gr4vy.String("2012"),
    },
  }

  transactionCreate := components.TransactionCreate{
    Amount:            amount,
    Currency:          currency,
    Country:           &country,
    ConnectionOptions: &connectionOptions,
    PaymentMethod:     &paymentMethod,
  }

  transaction, err := client.Transactions.Create(ctx, transactionCreate, nil, nil)
  ```

  ```java Java highlight={5-9} theme={"system"}
  CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
    .transactionCreate(TransactionCreate.builder()
      .amount(1299L)
      .currency("AUD")
      .connectionOptions(TransactionCreateConnectionOptions.builder()
        .latitudeLatitude(ConnectionOptionsLatitudeLatitude.builder()
          .promotionReference("2012")
          .build())
        .build())
      .paymentMethod(TransactionCreatePaymentMethod.of(RedirectPaymentMethodCreate.builder()
        .method("latitude")
        .redirectUrl("https://example.com/callback")
        .build()))
      .build())
    .call();
  ```

  ```php PHP highlight={5-9} theme={"system"}
  $transactionCreate = new TransactionCreate(
    amount: 1299,
    currency: 'AUD',
    country: 'AU',
    connectionOptions: new TransactionCreateConnectionOptions(
      latitudeLatitude: new ConnectionOptionsLatitudeLatitude(
        promotionReference: '2012'
      )
    ),
    paymentMethod: new RedirectPaymentMethodCreate(
      method: 'latitude',
      redirectUrl: 'https://example.com/callback'
    )
  );
  $response = $client->transactions->create($transactionCreate);
  ```

  ```python Python highlight={5-9} theme={"system"}
  transaction: models.Transaction = client.transactions.create(
    amount=1299,
    currency="AUD",
    country="AU",
    connection_options={
      "latitude-latitude": {
        "promotion_reference": "2012",
      },
    },
    payment_method={
      "method": "latitude",
      "redirect_url": "https://example.com/callback",
    }
  )
  ```

  ```ts TypeScript highlight={5-9} theme={"system"}
  const transaction = await client.transactions.create({
    amount: 1299,
    currency: "AUD",
    country: "AU",
    connectionOptions: {
      "latitude-latitude": {
        promotionReference: "2012",
      },
    },
    paymentMethod: {
      method: "latitude",
      redirectUrl: "https://example.com/callback",
    },
  });
  ```
</CodeGroup>