Skip to content
Console
On this page

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

FieldTypeWhat it is
namestringorgs/{org}/projects/{project}/envs/{env}/checkout_sessions/{checkout_session}.
uidstringchk_<cell><ulid>; never reused. Output only.
metaResourceMetaResource metadata.
subjectSubjectWho pays and is entitled. Required.
line_itemsLineItem[]What is bought: catalog prices by lookup key. One recurring price makes a subscription; one-time prices make an order. Required.
success_urlstringWhere the buyer lands after paying; {CHECKOUT_SESSION_ID} is replaced by the processor's session id. HTTPS only. Required.
cancel_urlstringWhere the buyer lands on cancel. HTTPS only.
currency_codestringThe currency to charge in, upper-case ISO 4217; default the processor's choice for the buyer among the prices' currencies.
localestringThe page language, for example en or zh-HK; default automatic.
metadatamap<string, string>Copied to the subscription or order, for example attribution (utm_source, ref). At most 20 keys.
allow_promotion_codesboolWhether the buyer may enter a promotion code.
buyer_country_codestringWhere 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_codesstring[]Countries whose shipping address the hosted page collects, upper-case ISO 3166-1 alpha-2. Empty means no shipping address is collected.
urlstringThe hosted page. Output only.
statestringopen, complete, or expired. Output only.
expire_timetimestampWhen the page stops accepting payment. Output only.
processor_session_idstringThe processor's session id. Output only.
denied_reasonstringWhy 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_codestringThe billing country the completed checkout was checked against, upper-case ISO 3166-1 alpha-2; empty until completion. Output only.
billing_subdivision_codestringThe 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_collectionCheckoutConsentCollectionThe consent the hosted page collects before it takes payment, for example a required tick for a withdrawal waiver or the terms of sale.
consentCheckoutConsentThe consent the buyer gave, recorded once the processor reports it. Output only.
customer_emailstringThe buyer's email address, once the hosted checkout has collected it. Output only.
shipping_addressShippingAddressThe physical delivery address, when shipping_country_codes was set and the hosted checkout has collected it. Output only.
amount_totalint64The processor's current total in minor units, when it has reported one. Output only.
payment_statusstringunpaid, paid, no_payment_required, or revoked; empty before settlement. Output only.
livemodeboolThe processor's live/test mode, once the session has reported it. Output only.
processor_payment_idstringThe processor payment this checkout produced; empty before settlement. Output only.
payment_methodstringstripe (default) or bank_transfer. Bank transfers never contact Stripe.
bank_transferBankTransferInstructionsFrozen beneficiary, amount, reference and bank-issued FPS QR instructions. Output only.
amount_taxint64Tax collected on the checkout session in minor units, when reported. Output only.
amount_discountint64Discount applied to the checkout session in minor units, when reported. Output only.
processor_invoice_idstringProcessor invoice id created by this checkout (typically for subscriptions). Output only.
processor_subscription_idstringProcessor subscription id created by this checkout, when mode is subscription. Output only.
customer_subscriptionstringMirrored CustomerSubscription resource name, when mode is subscription. Output only.
guestboolWhether this checkout was created without an account. Remains true after claim. Output only.
claimedboolWhether its guest ownership has been bound to an account. False is explicit. Output only.
claimed_bystringThe end-user id that claimed this checkout; empty before claim. Output only.
claimed_attimestampWhen ownership was claimed. The wire name preserves the served claim API. Output only.
claim_methodstringPossession proof used for the claim: claim_secret or verified_email. Output only.
claim_secretstringBrowser 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_attimestampWhen 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.

MethodCallWhat it does
POSTcreateCreates a hosted checkout for a subject.
GETgetGets a checkout session.
POSTexpireExpires an open hosted checkout so it can no longer be paid.
POSTrefundRefund 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