Embedding the Widget

Overview

The ElasticPay widget is a JavaScript class you mount onto a container element in your page. It renders a card input form and handles tokenization — card data never passes through your server.

Load the script

Add the widget script as an ES module:

<script type="module">
  import { ElasticPayCardWidget } from "https://pay.elasticpay.co/v1/widget.js";
  // initialize below
</script>

HTML setup

Add a container element where the widget will render:

<div id="card-widget"></div>
<button id="pay-button">Pay</button>

import { ElasticPayCardWidget } from "https://pay.elasticpay.co/v1/widget.js";

const widget = new ElasticPayCardWidget("card-widget", {
  apiUrl: "https://staging-api.elasticpay.co",
  publishableKey: "pk_sandbox_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  clientSecret: "pi_0abc123_secret_xyz987",
  onTokenize: (result) => {
    // Send result.id to your server to confirm the payment
    console.log("Payment method:", result.id);
  },
  onError: (error) => {
    console.error("Widget error:", error.message);
  },
});

Required config options:

Option	Description
`apiUrl`	`https://staging-api.elasticpay.co` (or `https://api.payfac.local` for local dev)
`publishableKey`	Your `pk_sandbox_...` or `pk_live_...` key
`clientSecret`	The `client_secret` from the payment intent

Data attributes approach

Configure the widget via HTML data attributes instead of JavaScript:

<div
  id="card-widget"
  data-api-url="https://staging-api.elasticpay.co"
  data-publishable-key="pk_sandbox_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  data-client-secret="pi_0abc123_secret_xyz987"
></div>

Then initialize with no config object:

const widget = new ElasticPayCardWidget("card-widget");

Hosted checkout (simplest option)

The hosted checkout redirects the customer to an ElasticPay-hosted payment page. No widget embedding required:

<!-- The hosted checkout expects a browser form POST (it sets an encrypted
     session cookie and 303-redirects to /v1/checkout/:payment_intent_id). -->
<form method="POST" action="https://pay.elasticpay.co/v1/checkout">
  <input type="hidden" name="payment_intent" value="pi_0abc123def456ghi789jkl012mn">
  <input type="hidden" name="client_secret" value="pi_0abc123_secret_xyz987">
  <input type="hidden" name="pk" value="pk_sandbox_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx">
  <input type="hidden" name="return_url" value="https://yoursite.com/payment/complete">
  <input type="hidden" name="cancel_url" value="https://yoursite.com/cart">
  <button type="submit">Pay</button>
</form>

After the customer completes payment, they are redirected to return_url with the payment intent ID as a query parameter.

For Australian bank account payments (BECS Direct Debit), use ElasticPayBecsWidget. It has the same API shape as the card widget:

import { ElasticPayBecsWidget } from "https://pay.elasticpay.co/v1/widget.js";

const widget = new ElasticPayBecsWidget("becs-widget", {
  apiUrl: "https://staging-api.elasticpay.co",
  publishableKey: "pk_sandbox_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  clientSecret: "pi_0abc123_secret_xyz987",
  onTokenize: (result) => {
    console.log("BECS payment method:", result.id);
  },
});