Invoices & Checkout API

Inspect invoices and create hosted Stripe / Radom checkout sessions

Every paid action on EntityEngine — entity setup, post-incorporation addons, change requests — produces an invoice. The Invoices API lets you fetch invoice details and spin up a hosted Stripe or Radom checkout session so your end customer can pay without a dashboard account.

Three payment paths

Bank transfer (default): when you create an entity without specifying a payment provider, the customer receives a standard Xero invoice email with bank details. Suitable for B2B flows where your customer is happy to wire funds.
Hosted Stripe checkout: passpayment_method: "card"on POST /entities/:id/invoice (or on the addon endpoint) and we return a hosted checkout URL that you forward to your customer. Cards only.
Hosted Radom checkout: same as above with payment_method: "crypto". Crypto.

Sandbox does not support hosted checkout

Sandbox API keys cannot create Stripe or Radom sessions — there is no live payment gateway in sandbox. Use POST /api/v1/sandbox/invoices/{invoiceId}/pay to simulate payment instead.

When to (re)generate a session

Stripe and Radom sessions cannot be amended after creation. Call POST /invoices/{id}/checkout-session when:

The customer abandoned the original session and you want to send a fresh link.
You added an addon to an unpaid setup invoice (the total changed).
The customer wants to switch from Stripe to Radom (or vice versa).

Endpoints

Related webhook events

Event	Fires when
payment.session_created	A new hosted checkout URL is generated for an invoice.
payment.received	An invoice is marked paid (Stripe, Radom or manual reconciliation).
payment.session_expired	A hosted checkout session expires before the customer pays.

End-to-end workflow

Create entity, issue invoice with hosted Stripe checkout, handle abandonment

# 1. Create the draft entity (no payment fields here).
curl -X POST https://app.entityengine.io/api/v1/entities \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jurisdiction_product_id": "jp_cayman_foundation",
    "name": "Acme Foundation"
  }'

# data.id → ent_...  data.status → "draft"

# 2. Issue the incorporation invoice and request a hosted Stripe checkout session.
curl -X POST https://app.entityengine.io/api/v1/entities/ent_.../invoice \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "card",
    "success_url": "https://chatbot.example.com/thanks",
    "cancel_url": "https://chatbot.example.com/cancelled",
    "customer_email": "founder@example.com",
    "customer_name": "Acme Foundation Ltd"
  }'

# data.invoice.id → inv_...
# data.checkout_session.checkout_url → forward to the customer.
# When they pay, you receive the payment.received webhook.

# 3. Customer abandons. Regenerate the link a week later:
curl -X POST https://app.entityengine.io/api/v1/invoices/inv_01HZX9P.../checkout-session \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "stripe",
    "success_url": "https://chatbot.example.com/thanks",
    "cancel_url": "https://chatbot.example.com/cancelled"
  }'