Guides

Direct API integration

If you want full control over the consumer experience, you can integrate directly with the ekko Climate API. This lets you calculate footprints, allocate funds to projects and manage reversals at any point in your journey. This is also how banks integrate, at the card-transaction level inside your own app, rather than at a checkout.

📘

When to use direct API integration

Use this path when you want to build a custom experience and handle the logic server-side. If you'd prefer a pre-built component, see the SDK options.

Integration flow

The direct API integration follows four steps:

  1. Create an organisation (if needed)
  2. Generate a quote (carbon or nature)
  3. Allocate funds
  4. Reverse a funds allocation (if the underlying transaction is refunded)

Step 1: Create an organisation

If your hierarchy requires child organisations, create them using POST /v3/organisations. This step is optional if you're working with your top-level organisation only.

See Create an organisation for details on when and how to use this endpoint.

Step 2: Generate a quote

Generate a carbon quote with POST /v3/quotes/carbon or a nature quote with POST /v3/quotes/nature. Each session uses one footprint type. The example below uses carbon.

Use POST /v3/quotes/carbon with the transaction details. The response includes:

  • The estimated carbon footprint in CO₂e, with localised equivalents
  • A carbon credit quote with locked-in amounts
  • Sustainability contribution data, expressed as effective rates

The response also returns a quoteId that you must pass when allocating funds in the next step.

{
  "organisationId": "1f9e36e2-fdf3-4d36-a6ae-a2a146ab5ca1",
  "locale": "en-GB",
  "consumer": {
    "reference": "consumer_123",
    "countryCode": "GBR"
  },
  "merchant": {
    "name": "Blossom & Bloom",
    "mcc": "5992",
    "address": {
      "line1": "45 Rosewood Avenue",
      "city": "London",
      "postalCode": "SW1A 1AA",
      "countryCode": "GBR"
    }
  },
  "transaction": {
    "amount": 47.97,
    "currencyCode": "GBP"
  }
}

You can omit the merchant object if the organisation already has an MCC set at organisation level.

📘

Nature quote

To estimate biodiversity impact instead, call POST /v3/quotes/nature. It returns a Nature Footprint in Mean Species Abundance (MSA) with a four-category breakdown, plus contribution data. Nature quotes don't return a credits block. See Create a nature quote and Footprinting.

Round-ups and fixed-value contributions

The quote response includes a contribution section with the effective rates used to split any contribution. You can use these rates to calculate round-up or fixed-value contribution amounts for consumer-facing display.

"contribution": {
  "effectiveRates": {
    "impact": 0.5,
    "impactTax": 0.0,
    "serviceFee": 0.2,
    "serviceFeeTax": 0.2
  }
}

The effective rates show how any contribution amount is split. For example, if the consumer's transaction is £47.97 and you want to offer a round-up to £48.00, the contribution amount is £0.03. Apply the rates to show how that £0.03 is distributed across impact, service fee and sales tax where applicable.

When allocating funds in the next step, you only need to pass the total contribution amount (e.g. 0.03). ekko calculates the full breakdown based on the quote.

See Create a carbon quote for the full request and response reference.

Step 3: Allocate funds

Once the consumer has chosen to purchase credits, make a contribution or both, use POST /v3/funds/allocations to allocate the funds. You must include the quoteId from the previous step.

You can send credits, a contribution or both in the same request:

  • Credits are allocated to specific projects using projectIds
  • Contributions are allocated to impact partners using impactPartnerIds. The impact partner decides how to distribute funds across their projects.
{
  "organisationId": "1f9e36e2-fdf3-4d36-a6ae-a2a146ab5ca1",
  "quoteId": "a6711057-1b63-41e0-81c3-24c02c5ef63b",
  "currencyCode": "GBP",
  "credits": {
    "amount": 0.518,
    "projectIds": [
      "5cc398c1-baa2-4504-a95e-f925c8c7ac9c"
    ]
  },
  "contribution": {
    "amount": 1.0,
    "impactPartnerIds": [
      "abdc3eb2-5464-4630-b0c8-b40dac0b930e"
    ]
  }
}

The response returns a fundsAllocationId that you should store for reconciliation and reversals.

See Allocate funds to a project for the full request and response reference.

Step 4: Reverse a funds allocation

If the underlying transaction is refunded or cancelled, reverse the allocation using POST /v3/funds/allocations/{id}/reverse.

This creates a negative record linked to the original allocation.

See Reverse a funds allocation for details.

Banking patterns

Banks integrate through this same API. You are the commercial partner, your cardholders are the consumers, and the merchant in each quote is wherever the cardholder spent. You already hold the merchant category code (MCC) for each card transaction, which is the main input the quote needs.

Common patterns:

  • Per-transaction footprint. Generate a quote for a card transaction using its merchant MCC, amount and currency, then show the footprint in your app.
  • Round-ups. Use the contribution effective rates to round a transaction up to the nearest unit and allocate the difference, the same mechanics shown in Step 2 and Step 3 above.

The quote and allocation endpoints are the same as above. What changes is when and where you call them: per card transaction, not at a checkout.

Reconciliation

Use GET /v3/funds/allocations to retrieve a full ledger of allocations and reversals. You can filter by date range, project, impact partner or consumer reference.

See Reconciliation for details.