Embedded Checkout

An embedded-checkout session is the server-side counterpart to the @easylabs/embedded-checkout browser widget. Your server creates the session and returns the client_secret to the browser; the browser calls validate and confirm directly with that secret (no API key needed in client code).

Accessed via client.embedded_checkout.

Methods

`create(**body)`

POST /embedded-checkout. Server-side. Returns the session including the client_secret.

session = client.embedded_checkout.create(
  line_items: [{ price_id: "price_…", quantity: 1 }]
)

return_to_browser(session[:client_secret])

`retrieve(id)`

GET /embedded-checkout/:id. Server-side session lookup.

client.embedded_checkout.retrieve("sess_…")

`crypto_status(id)`

GET /embedded-checkout/:id/crypto-status. Polls the on-chain status for crypto sessions.

client.embedded_checkout.crypto_status("sess_…")

`validate(client_secret:, parent_origin: nil)`

POST /embedded-checkout/validate. Public endpoint — authenticates via the session's client_secret and skips the X-Easy-Api-Key header entirely, so it's safe to call from a browser-like context. The SDK still exposes it for completeness (e.g. server-side smoke tests).

client.embedded_checkout.validate(
  client_secret: "cs_…",
  parent_origin: "https://shop.example.com"
)

`confirm(client_secret:, source:, customer_details:)`

POST /embedded-checkout/confirm. Public endpoint — same auth behaviour as validate.

client.embedded_checkout.confirm(
  client_secret:    "cs_…",
  source:           { type: "PAYMENT_CARD", tokenId: "tok_…" },
  customer_details: { first_name: "Ada", last_name: "Lovelace", email: "ada@example.com" }
)

`config`

GET /embedded-checkout/config. Returns the merchant-level embedded config (e.g. allowed_origins).

client.embedded_checkout.config

`update_config(allowed_origins: nil)`

PATCH /embedded-checkout/config.

client.embedded_checkout.update_config(allowed_origins: ["https://shop.example.com"])

def create_checkout_session(price_id)
  session = client.embedded_checkout.create(
    line_items: [{ price_id: price_id, quantity: 1 }]
  )

  { client_secret: session[:client_secret] }
end

Lock down `allowed_origins`

client.embedded_checkout.update_config(
  allowed_origins: ["https://shop.example.com", "https://staging.shop.example.com"]
)