Checkout sessions
A Checkout Session is a hosted page where a subject pays for catalog prices.
A Checkout Session is a hosted page where a subject pays for catalog prices. Money creates the processor's session on the environment's merchant account and returns its URL.
Service Sylphx Money · Resource type money.sylphx.com/CheckoutSession · Name pattern orgs/{org}/projects/{project}/envs/{env}/checkout_sessions/{checkout_session} · Shape record
Fields
| Field | Type | What it is |
|---|---|---|
name | string | orgs/{org}/projects/{project}/envs/{env}/checkout_sessions/{checkout_session}. |
uid | string | chk_<cell><ulid>; never reused. Output only. |
meta | ResourceMeta | Resource metadata. |
subject | Subject | Who pays and is entitled. Required. |
line_items | LineItem[] | What is bought: catalog prices by lookup key. One recurring price makes a subscription; one-time prices make an order. Required. |
success_url | string | Where the buyer lands after paying; {CHECKOUT_SESSION_ID} is replaced by the processor's session id. HTTPS only. Required. |
cancel_url | string | Where the buyer lands on cancel. HTTPS only. |
currency_code | string | The currency to charge in, upper-case ISO 4217; default the processor's choice for the buyer among the prices' currencies. |
locale | string | The page language, for example en or zh-HK; default automatic. |
metadata | map<string, string> | Copied to the subscription or order, for example attribution (utm_source, ref). At most 20 keys. |
allow_promotion_codes | bool | Whether the buyer may enter a promotion code. |
buyer_country_code | string | Where the buyer is, upper-case ISO 3166-1 alpha-2, when the caller knows it (for example from the request's IP address). A country the environment's checkout policy denies is refused here, before any page is made, unless the policy lets a business buy. Not trusted for anything else: the billing address the buyer gives is checked again when the payment completes. |
shipping_country_codes | string[] | Countries whose shipping address the hosted page collects, upper-case ISO 3166-1 alpha-2. Empty means no shipping address is collected. |
url | string | The hosted page. Output only. |
state | string | open, complete, or expired. Output only. |
expire_time | timestamp | When the page stops accepting payment. Output only. |
processor_session_id | string | The processor's session id. Output only. |
denied_reason | string | Why a completed checkout was refused and refunded instead of delivered: country_denied (the billing country is on the checkout policy's list) or country_unknown (no billing country to check). Empty otherwise. Output only. |
billing_country_code | string | The billing country the completed checkout was checked against, upper-case ISO 3166-1 alpha-2; empty until completion. Output only. |
billing_subdivision_code | string | The billing state or province, upper-case, kept only for the countries whose tax thresholds are per subdivision (US, CA); empty otherwise. Nothing else of the buyer's address is stored. Output only. |
consent_collection | CheckoutConsentCollection | The consent the hosted page collects before it takes payment, for example a required tick for a withdrawal waiver or the terms of sale. |
consent | CheckoutConsent | The consent the buyer gave, recorded once the processor reports it. Output only. |
customer_email | string | The buyer's email address, once the hosted checkout has collected it. Output only. |
shipping_address | ShippingAddress | The physical delivery address, when shipping_country_codes was set and the hosted checkout has collected it. Output only. |
amount_total | int64 | The processor's current total in minor units, when it has reported one. Output only. |
payment_status | string | unpaid, paid, no_payment_required, or revoked; empty before settlement. Output only. |
livemode | bool | The processor's live/test mode, once the session has reported it. Output only. |
processor_payment_id | string | The processor payment this checkout produced; empty before settlement. Output only. |
payment_method | string | stripe (default) or bank_transfer. Bank transfers never contact Stripe. |
bank_transfer | BankTransferInstructions | Frozen beneficiary, amount, reference and bank-issued FPS QR instructions. Output only. |
amount_tax | int64 | Tax collected on the checkout session in minor units, when reported. Output only. |
amount_discount | int64 | Discount applied to the checkout session in minor units, when reported. Output only. |
processor_invoice_id | string | Processor invoice id created by this checkout (typically for subscriptions). Output only. |
processor_subscription_id | string | Processor subscription id created by this checkout, when mode is subscription. Output only. |
customer_subscription | string | Mirrored CustomerSubscription resource name, when mode is subscription. Output only. |
guest | bool | Whether this checkout was created without an account. Remains true after claim. Output only. |
claimed | bool | Whether its guest ownership has been bound to an account. False is explicit. Output only. |
claimed_by | string | The end-user id that claimed this checkout; empty before claim. Output only. |
claimed_at | timestamp | When ownership was claimed. The wire name preserves the served claim API. Output only. |
claim_method | string | Possession proof used for the claim: claim_secret or verified_email. Output only. |
claim_secret | string | Browser possession proof, returned only by create and its authorized retry while active. Never returned by get, list, or claim; never stored in plaintext. Output only. Never returned again. |
claim_secret_expires_at | timestamp | When the browser possession proof expires. The existing wire name is retained. Output only. |
Methods
Every method of the collection, in the registry's order, with the scope it needs. The full request, response and examples are one link away.
| Method | Call | What it does |
|---|---|---|
POST | create | Creates a hosted checkout for a subject. |
GET | get | Gets a checkout session. |
POST | expire | Expires an open hosted checkout so it can no longer be paid. |
POST | refund | Refund all or part of a paid one-time checkout. |
create
Creates a hosted checkout for a subject.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/checkout_sessions · scope billing:write · effect write · Request, response and examples
get
Gets a checkout session.
GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/checkout_sessions/checkout-session · scope billing:read · effect read · Request, response and examples
expire
Expires an open hosted checkout so it can no longer be paid.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/checkout_sessions/checkout-session:expire · scope billing:write · effect write · Request, response and examples
refund
Refund all or part of a paid one-time checkout.
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/checkout_sessions/checkout-session:refund · scope billing:write · effect write · Request, response and examples