Embedded Checkout
Embedded Checkout — methods, parameters, and examples for easy-sdk (pip).
Embedded Checkout lets you render a fully-managed checkout flow in an
iframe inside your own UI. Your server creates a session via the
x-easy-api-key, hands the resulting client_secret to the browser,
and the iframe takes care of the rest.
Namespace: client.embedded_checkout.
Two of the methods below (validate, confirm) are client-side
methods that authenticate via the session's client_secret instead
of the SDK's API key. They're included on the Python SDK for parity
with the JS SDK's surface and for server-rendered flows that need to
proxy these calls.
Methods
create_session
session = client.embedded_checkout.create_session(
items=[{"price_id": "price_abc", "quantity": 1}],
return_url="https://example.com/checkout/return",
idempotency_key="ecs-cart-2025-01-01-001",
)
print(session.id, session.client_secret)Returns: EmbeddedCheckoutSession. Hand client_secret to the
browser; do not log it.
retrieve_session
status = client.embedded_checkout.retrieve_session("ecs_123")
print(status.status, status.payment_status)Returns: EmbeddedCheckoutSessionStatus.
crypto_status
crypto = client.embedded_checkout.crypto_status("ecs_123")
print(crypto.status, crypto.tx_signature)Returns: CryptoPaymentStatus — for sessions paid via on-chain assets.
validate (client-side)
ok = client.embedded_checkout.validate(
client_secret="ecs_secret_xyz",
parent_origin="https://example.com",
)
print(ok.valid)Returns: ValidateEmbeddedCheckoutSessionResponse. Sends no API key
— authenticates via client_secret. Use server-side only when proxying
the iframe call.
confirm (client-side)
result = client.embedded_checkout.confirm(
client_secret="ecs_secret_xyz",
payment_method={"type": "PAYMENT_CARD", "token_id": "tok_abc"},
idempotency_key="confirm-ecs_123-1",
)Returns the raw confirmation payload (dict). Same authentication
note as validate.
get_config
config = client.embedded_checkout.get_config()
print(config.allowed_origins)Returns: EmbeddedCheckoutConfig.
update_config
config = client.embedded_checkout.update_config(
allowed_origins=["https://example.com", "https://staging.example.com"],
idempotency_key="ecs-config-2025-01-01",
)Returns the updated EmbeddedCheckoutConfig.
Object shape
EmbeddedCheckoutSession:
| Field | Type |
|---|---|
id | str |
client_secret | str | None |
status | str | None |
expires_at | str | None |
return_url | str | None |
created_at, updated_at | str | None |
EmbeddedCheckoutSessionStatus: id, status, payment_status.
CryptoPaymentStatus: status, tx_signature, payment_address,
chain, asset, amount — all str | None.
EmbeddedCheckoutConfig: allowed_origins, updated_at.
Examples
Server endpoint that mints a session for the browser
@app.post("/api/checkout/session")
def create_checkout_session(request):
cart = build_cart_from(request.user)
session = client.embedded_checkout.create_session(
items=cart.items,
return_url=f"https://example.com/checkout/{cart.id}/return",
idempotency_key=f"ecs-{cart.id}",
)
return {"client_secret": session.client_secret}Poll session status server-side after redirect
status = client.embedded_checkout.retrieve_session(session_id)
if status.payment_status == "succeeded":
fulfill(session_id)