Lune Pay

The Lune API and our approach

Lune provides a single API for use in-app and web channels to fetch, mutate, and deliver the data necessary to offset CO₂ emissions across a range of verticals.

Our API-first approach allows our customers to embed carbon offsetting and emission calculations into logistics, payments, and fintech platforms to deliver a unique and programmatically driven experience that brings climate into our clients' products.

Overview

Lune Pay is a hosted payment page that can be used for one-time or recurring payments. Customers can use Lune Pay if they wish to collect payment for carbon credits directly from their customers.

Every Lune Pay payment is linked to an Account or Client Account.

Lune Pay enables customers to stay out of the flow of funds required to settle Lune invoices and therefore removes the need to manage clients' monies for offsetting.

In this guide, you will learn how to:

1. Generate a Lune Pay link to redirect users to
2. Handling redirection to your app

Who is this guide for?

This guide is primarily aimed at developers looking to integrate CO₂ removal into an existing end-user experience.

Feel free to contact our support team if you encounter any issues integrating our payments use case.

Concepts

• Client account - You must create a Client account for each client to define their basic characteristics, such as name, currency, and beneficiary. Clients will be provided Lune defaults
• Lune defaults - Lune has provided a default Project bundle for each of our clients. Every order will be placed against the following projects and ratios:
  • Conserving forests in Asia - 95%
  • Ocean Carbon Removal - 5%
• Project bundle - Group of offsetting projects with similar characteristics., e.g., Conserving forests in Asia and Ocean Carbon Removal

Flow

Getting an API key

First, head over to the Lune dashboard and generate a new API key.

1. Navigate to https://dashboard.lune.co/developers

2. Select New Test API Key, enter a value in the Name field, and select an account from Default account

3. Select Save

4. Copy your API key, as you'll need it to interact with the Lune API

Create a client account

A client account is required for each of your clients and defines their basic characteristics, for example, the currency used to display emission offsetting prices.

Store and map the client account id to your client in your database.

Client accounts are optional but recommended for B2B businesses and discouraged for B2C businesses. Learn about their benefits and how to use either.

Sample request

You can optionally pass in beneficiary to link a client account to the legal entity receiving the carbon offset.

Sample response

A successful request will return a unique id, which you will need to pass in later interactions with the Lune API.

Where:

• id is the unique identifier for each of your clients, which you must map in your code base
• name is a name that you will use to identify your client and present offsetting options to
• currency defines the currency used to display the price for each offsetting option
• type defines the type of account. Use test for your playground
• beneficiary is the legal entity shown on the Carbon Offset Certificate and carbon registries

Following a successful response, a client account will be added to your dashboard:

You can access the dedicated client account page by appending the id to /client-account e.g., https://dashboard.lune.co/settings/client-accounts/K4enjo9g08vx3MpjnbpPrEZ57XJkDVdb.

Sample request

curl "https://api.lune.co/v1/accounts/client" \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '
    {
      "name": "MY TEST COMPANY",
      "currency": "USD",
      "beneficiary": "MY TEST COMPANY INC"
    }'

Sample response

{
  "id": "K4enjo9g08vx3MpjnbpPrEZ57XJkDVdb",
  "name": "MY TEST COMPANY",
  "currency": "USD",
  "balance": "0",
  "balance_outstanding": "0",
  "type": "test",
  "scope": "client_account",
  "beneficiary": "MY TEST COMPANY INC",
  "organisation_id": "42O097M13DKvo5pmlJYZjmVlGzqJwXbE",
  "bundle_portfolio_id": null,
  "logo": null
}

Generate and embed a Lune Pay URL

Lune Pay URLs have the following format: https://pay.lune.co/<CLIENT_ACCOUNT_ID>.

Where:

• <CLIENT_ACCOUNT_ID> is the unique identifier for the client

Successful payments credit the Client Account identified by <CLIENT_ACCOUNT_ID>.

Configuration

Lune Pay can be configured by providing several optional query parameters:

• quantity is used to prefill the mass to offset in tCO₂
• redirect_url is the url to redirect to once the payment completes
• redirect_label is your company/service name. It is used to populate a 'Back to <redirect_label>' button
• external_id is a customer-defined id. It serves two purposes:
  1. It enforces flow uniqueness. If a customer has completed a payment with a specific external_id, it cannot complete additional payments with the same external_id
  2. it is appended to redirect_url as a query parameter. Customers can use external_id for flow reconciliation
• bundle_id is the id of the bundle or bundles (multiples are supported) to display. If not set, the account's default bundle selection is displayed. You can extract bundle ids by using the API's list project bundles endpoint

Embed Lune Pay URL

Embed Lune Pay's URL in your app in a button.

Clicking on the button should redirect the user to Lune Pay's URL.

Sample URL

https://pay.lune.co/zK7ExbX0ejgLM5YR3Qp3B2mVnW9rawPl?quantity=100&bundle_id=xWaKJL3okjD46VpJ4yGXnQNZRe1vzP0w&bundle_id=15xRmEXZq0NnJLpPnydPr7akGOjV9g3z&bundle_id=L0M3zv7Qr2OGRqY9WAVdbwKPx5XWao64

Handle redirection to your app

On successful payment, the user is shown a confirmation page.

Clicking Back to <redirect_label> redirects the user to redirect_url.

The following query parameters are appended to redirect_url:

• external_id if it was provided initially. external_id can be used to identify the flow
• temporary_id is a unique temporary identifier representing the payment. The id is valid for 15 minutes and allows clients to retrieve payment details without authentication using the get payment by temporary id endpoint. This parameter is useful if a customer wants to build a frontend confirmation screen showing Lune Pay information