🔄

This page reflects the current API behaviour. Some details may change as v3 is finalised.

Call POST /v3/impactpay/sessions to create a session for the hosted ImpactPay experience. The response returns a hosted impactPayLink that you share with the consumer, along with the calculated footprint and credit quote.

For an overview of how ImpactPay works and what consumers see, see ImpactPay overview.

📘

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

Making the request

The request requires organisationId, locale, consumer and transaction. You can optionally set impactType to carbon or nature (defaults to carbon if omitted).

{
  "organisationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "impactType": "carbon",
  "locale": "en-GB",
  "consumer": {
    "reference": "consumer_123",
    "postalCode": "SW1A 1AA",
    "city": "London",
    "countryCode": "GBR"
  },
  "merchant": {
    "name": "Blossom & Bloom",
    "mcc": "5992",
    "address": {
      "line1": "Ground floor",
      "line2": "45 Rosewood Avenue",
      "city": "London",
      "postalCode": "SW1A 1AA",
      "countryCode": "GBR"
    }
  },
  "transaction": {
    "amount": 47.97,
    "currencyCode": "GBP"
  },
  "orderItems": [
    {
      "itemReference": "line_1",
      "sku": "POT_LARGE",
      "description": "Flower pot large",
      "category": "pots",
      "quantity": 3,
      "unitPrice": {
        "value": 15.99,
        "currencyCode": "GBP"
      }
    }
  ],
  "projectFilters": {
    "matchConsumerLocation": true
  }
}

orderItems are optional and not used in the footprint calculation, but are recommended for analytics and reporting.

Set projectFilters.matchConsumerLocation to true to prioritise projects near the consumer’s location.

The response

A successful request returns HTTP 201 with the hosted link, the calculated footprint and a credit quote.

{
  "quoteId": "4c02038e-4b93-4d02-9a21-6478370e3a7f",
  "footprint": {
    "co2eGrams": 18251,
    "co2eOunces": 644,
    "equivalents": [
      {
        "key": "phone",
        "value": 106,
        "template": "That's like using your mobile phone for 106 hours"
      },
      {
        "key": "car",
        "value": 81,
        "template": "That's like driving 81 km by car"
      }
    ]
  },
  "credits": {
    "totalAmount": 0.518
  },
  "impactPayLink": "https://impactpay.ekko.earth/en-GB/carbon?referenceId=4c02038e-4b93-4d02-9a21-6478370e3a7f",
  "locale": "en-GB",
  "currencyCode": "GBP",
  "expiresAt": "2026-01-07T14:30:00Z"
}

impactPayLink is the URL you share with the consumer. The session is valid until the expiresAt timestamp. After that, you’ll need to create a new session.

The footprint and credits data is also returned so you can display it alongside the link, for example in an email showing the consumer their footprint before they click through.

⚠️

Sessions expire at the time shown in expiresAt. Create a new session if the current one has expired.

How consumers reach ImpactPay

The ImpactPay session endpoint is used in the ImpactPay URL integration path. Your backend creates the session, receives the impactPayLink and shares it with the consumer via email, SMS, receipt or any other channel. The consumer follows the link to the hosted ImpactPay page.

If you’re using the post-purchase SDKs instead, the SDK creates its own session. You don’t call this endpoint directly. See Post-purchase web SDKs for that flow.

For more on sharing the link, see ImpactPay URL.

Reconciliation

Since ekko processes the payment on the hosted page, contributions appear in your funds allocation records automatically. Set up webhooks to receive notifications when a consumer completes a contribution or when a reversal occurs.

Use GET /v3/funds-allocations to retrieve records for reconciliation. See Reconciliation for details.