Guides

Post-purchase web SDKs

šŸ”„

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

Offer an impact experience after payment using ekko's postā€‘purchase SDKs. ekko renders the components serverā€‘side, and the SDK provides a simple way to drop them into your confirmation flow.

ā„¹ļø

See our post-purchase SDKs in action at https://pwa.ekko.earth/

When to use

  • You want a hosted impact experience
  • You prefer ekko to process the contribution payment separately from the main payment
  • You need fast time to value with low engineering effort

Options at a glance

OptionPlacement in journeyEffortBest for
Full page takeover SDKBetween payment complete ā†’ order confirmationMediumA focused, immersive impact journey
Embedded SDKInside your existing confirmation pageMediumA nativeā€‘feeling module within your own layout

How they work (shared flow)

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

  2. Create a post-purchase session. Your backend calls POST /v3/post-purchase/sessions with order context and merchant details. You receive a sessionId and a short-lived clientSecret to initialise the SDK.

  3. Initialise the SDK on the client. Pass the clientSecret to the SDK to authenticate the session. ekko server-side renders the component.

  4. Consumer reviews and contributes. Consumers see their footprint, learn more about projects, and can make a contribution using ekko's hosted payment page.

  5. Set up webhooks. To keep your systems in sync, ekko provides webhook events for post-purchase payments:

    • IMPACT_PAYMENT ā†’ fired when a contribution payment is successfully processed
    • IMPACT_PAYMENT_REVERSAL ā†’ fired when a processed payment is refunded or voided

  6. Records and reconciliation. Contributions, credits and any reversals appear in your reconciliation records.

What's shared across both SDKs

  • Server-side rendered content and visuals that stay up to date as we apply new learnings and local insights - without you needing to make changes
  • Shortā€‘lived clientSecret for secure initialisation
  • Resilience features so existing confirmation pages remain usable if the SDK fails to load