game.gm.commerce.stripe — ai.intergraph/game-master 0.1.24

Thin wrapper around Stripe REST API + webhook signature verification. v1 supports Hosted Checkout only; all funds land in our account. Connect migration is additive — see docs/stripe.md.

create-account-link clj

(create-account-link {:keys [secret-key account-id refresh-url return-url]})

Creates a hosted Account Link so a player can complete Express onboarding. Returns {:ok? true :url ...} or {:ok? false :status ... :error ...}.

create-checkout-session clj

(create-checkout-session {:keys [secret-key checkout-id buyer game-name
                                 line-items success-url cancel-url
                                 on-behalf-of]})

Creates a Stripe Hosted Checkout Session. Returns {:ok? true :id ... :url ...} on success, {:ok? false :status ... :error ...} otherwise. line-items is a vector of {:title :amount :currency :quantity} (amount is minor units). game-name is stamped into session metadata so the webhook can resolve the game.

on-behalf-of is REQUIRED — the game's Stripe connected-account id. It names the game as merchant-of-record (games-as-merchants Model B); funds still settle to the platform (separate charges & transfers, no transfer_data). A blank value returns {:ok? false :error-code "merchant-account-required"} WITHOUT calling Stripe, so no session can exist for a charge the platform would be merchant of record for.

The checkout route already refuses to proceed without a merchant account, but that is a guarantee about one caller. This is the structural one: no future caller can bypass it.

create-connected-account clj

(create-connected-account {:keys [secret-key owner-id game-name email
                                  house-account]})

Creates a Stripe Express connected account for a player's payouts. owner-id and game-name are stamped into metadata so the account.updated webhook can resolve the account back to a (owner, game) payout record via the connect endpoint. Returns {:ok? true :id "acct_..."} or {:ok? false :status ...}.

create-customer-portal-session clj

(create-customer-portal-session {:keys [secret-key connected-account-id
                                        customer-id return-url subscription-id
                                        subscription-item-id target-price-id]})

Create Stripe's hosted billing portal in the seller's connected account.

create-embedded-direct-checkout-session clj

(create-embedded-direct-checkout-session
  {:keys [secret-key connected-account-id checkout-id checkout-batch-id buyer
          game-name commerce-adapter fulfillment-ref line-items
          application-fee-amount application-fee-bps market-subscription-id
          plan-sku return-url idempotency-key]})

Creates an embedded, card-only Checkout Session as a direct charge on a Standard connected account. One-time payments use an application fee amount; subscriptions use an application fee percentage on every invoice.

The client secret is returned to the authenticated caller but must never be persisted in Market state or logs. idempotency-key identifies one creation attempt and makes request retries safe.

create-refund clj

(create-refund {:keys [secret-key payment-intent-id amount reason refund-id
                       order-id checkout-id game-name connected-account-id]})

Refunds amount (minor units) of a PaymentIntent back to the buyer. Omit amount for a full refund. refund-id is passed as the Stripe Idempotency-Key header AND stamped into metadata, so a retried refund never double-refunds and a charge.refunded webhook correlates straight back to the market refund record.

Model B note: charges are created with on_behalf_of and no transfer_data, so the funds sit in the Intergraph platform balance and a plain platform-key refund is correct — no refund_application_fee / reverse_transfer. A short platform balance surfaces as error-code "balance_insufficient".

Returns {:ok? true :id "re_..." :status <stripe status>} on success, or {:ok? false :status ... :error ... :error-code <stripe code>}.

create-transfer clj

(create-transfer {:keys [secret-key amount currency destination withdrawal-id
                         game-name player-name]})

Transfers amount (minor units) from the platform balance to a connected account (separate charges & transfers model). withdrawal-id is passed as the Stripe Idempotency-Key header AND stamped into metadata so transfer.* webhooks correlate back to the withdrawal. Returns {:ok? true :id "tr_..."} on success. On failure returns {:ok? false :status ... :error ... :error-code <stripe code>}; a short platform balance surfaces as error-code "balance_insufficient".

exchange-oauth-code clj

(exchange-oauth-code {:keys [secret-key code]})

expire-checkout-session clj

(expire-checkout-session {:keys [secret-key session-id]})

Expires an open Checkout Session so it can no longer be paid. POST /v1/checkout/sessions/{id}/expire.

Used to drain sessions created before the merchant gate shipped: those carry no merchant-account-id stamp, so if one completes afterwards the webhook has nothing to verify against and must grandfather it. Expiring them narrows that window. Returns {:ok? true :status "expired"} or {:ok? false :status ... :error ...}.

fetch-charge-refunds clj

(fetch-charge-refunds {:keys [secret-key charge-id connected-account-id]})

Fetch the refund objects for a charge. Recent charge.refunded webhook objects omit the embedded refunds list, including for partial refunds.

fetch-invoice-for-payment-intent clj

(fetch-invoice-for-payment-intent {:keys [secret-key payment-intent-id
                                          connected-account-id]})

Resolve a subscription PaymentIntent through Stripe's Invoice Payments API. Recent Stripe API versions omit the legacy PaymentIntent.invoice field.

fetch-payment-fee clj

(fetch-payment-fee {:keys [secret-key payment-intent-id]})

Resolve the actual Stripe processing fee for a completed PaymentIntent by expanding its latest charge's balance transaction. Funds land net of this fee in our account, so it is the platform's real cost of the sale.

Returns {:ok? true :amount <minor-units> :currency <ISO>} on success, or {:ok? false :status :error} so callers can degrade gracefully (no fee recorded → platform simply absorbs it, as before).

fetch-payment-intent clj

(fetch-payment-intent {:keys [secret-key payment-intent-id
                              connected-account-id]})

Fetch a PaymentIntent with its latest charge's balance transaction expanded. Returns {:ok? true :payment-intent <object>} on success, or {:ok? false :status ... :error ...} on failure. For a direct charge, pass connected-account-id so Stripe resolves the PaymentIntent in the seller's account rather than the platform account.

fetch-refund clj

(fetch-refund {:keys [secret-key refund-id]})

Reads a refund back from Stripe. Used by the recovery path for refunds left :reserved because the process died before/while calling Stripe.

list-open-checkout-sessions clj

(list-open-checkout-sessions {:keys [secret-key starting-after limit]})

Lists OPEN Checkout Sessions, newest first. GET /v1/checkout/sessions?status=open.

Only open sessions can be expired, so the filter is not a convenience — a completed or already-expired session would 400 on expire. Returns {:ok? true :sessions [...] :has-more? bool}; page with :starting-after using the last id from the previous page.

oauth-authorize-url clj

(oauth-authorize-url {:keys [client-id redirect-uri state]})

parse-event clj

(parse-event raw-body)

Parse a raw Stripe webhook JSON body into a Clojure map with keyword keys.

payment-intent-available-on clj

(payment-intent-available-on payment-intent)

The Unix timestamp (seconds) the charge's funds move from pending -> available in the platform balance, read from the latest charge's balance transaction. This is the maturity date a player's earnings from this charge become withdrawable. Returns nil when not yet known.

payment-intent-fee clj

(payment-intent-fee payment-intent)

Extract the actual Stripe fee from a fetched PaymentIntent object.

payment-intent-on-behalf-of clj

(payment-intent-on-behalf-of payment-intent)

The connected account Stripe treats as the settlement merchant for this charge. Returns the acct_ id string, or nil when the charge is platform-attributed. Stripe returns a bare id unless the field was expanded, so handle both.

recurring-line-items? clj

(recurring-line-items? line-items)

True when every line carries :recurring. Mixed carts are refused upstream (market rejects them at checkout), so this is a total question: a session is either a subscription or a payment, never both.

refund-application-fee clj

(refund-application-fee {:keys [secret-key payment-intent-id
                                connected-account-id amount refund-id]})

Return part of a direct charge's application fee to its connected seller. The Market refund id is the idempotency key. This is separate from the buyer refund and always runs on the platform account.

resolve-checkout-payment-intent clj

(resolve-checkout-payment-intent {:keys [secret-key session-id
                                         connected-account-id checkout-id
                                         game-name amount]})

Resolve the original paid invoice of a seller-direct subscription Checkout. Stripe Checkout's payment_intent is nil for subscription mode, and recent Invoice objects no longer expose a legacy payment_intent field. Require one paid invoice payment matching the Market checkout gross before refunding.

retrieve-account clj

(retrieve-account {:keys [secret-key account-id]})

Fetches a connected account to read payouts_enabled / requirements. Returns {:ok? true :account <object>} or {:ok? false :status ... :error ...}.

retrieve-subscription clj

(retrieve-subscription {:keys [secret-key connected-account-id
                               subscription-id]})

verify-signature clj

(verify-signature raw-body sig-header secret)

(verify-signature raw-body sig-header secret now-seconds)

Returns {:ok? true} when the Stripe-Signature header validates raw-body against secret, else {:ok? false :reason :missing|:malformed|:expired|:mismatch}. now-seconds defaults to current wall clock; pass explicitly to test.