Payments & refunds

Choose native payment instructions or record money the studio actually collected elsewhere. Both models preserve Podyx's admission, pricing, approval and fulfillment rules.

Native payment capabilities

Accept a complete native booking, then read the checkout. Native instructions can be no_payment_required, cash, stripe_elements, square_card or redirect. Use the returned public SDK options, connected-account/location, client secret, amount and browser capability for the selected instruction kind.

Keep studio keys and private provider credentials on your backend. Deliver only the public instruction to the authorized customer's browser. Cash and zero/credit-funded paths still obey their native admission/approval policy. Do not create fake provider or payment IDs to make the paths look alike.

For Stripe Elements, ask Podyx's operator for the Podyx Stripe platform's publishable key, available from that platform's Stripe Dashboard API keys. Configure this public value in your frontend as stripePublishableKey, using the same test/live environment as the checkout. Booking checkout instructions do not return it; a key from an unrelated Stripe account is not a substitute. Initialize Stripe with this configured key and the returned provider_options.connected_account_id, mount Elements with client_secret and use the provider's browser confirmation API.

For Square, load its Web Payments SDK for the returned environment/application/location, tokenize in the browser and submit square_token through your backend to checkout payment tokens. Never send the studio key to either browser SDK.

Confirmation, retry and unpaid cancellation are separate commands under the checkout's /payment/ subresource. They accept the published body (empty {} where specified) and each gets its own persisted request UUID. Retry uncertain delivery of one command with that command's original UUID. Read current state after provider work is queued; a browser callback does not prove settlement.

Studio-collected money

Create an external checkout with the same complete ordinary booking selection. This chooses provider=external, settlement_mode=off_platform; it does not change the configured native provider or relabel a Stripe/Square/cash payable.

Read the external checkout for the real payment ID and authoritative amount/currency. Collect money through the studio's own process, then report the actual collection. The collection_id identifies the real collection independently of the HTTP request UUID. Persist it through retries, key rotation and refunds; a merchant reference cannot replace it.

For an existing payment ID, omitting both amount and currency reports the entire positive outstanding balance, frozen at acceptance. A covered payable refuses that default. Use explicit actual amounts/currency for partial collection or overcollection. Successful refunds reopen the balance; pending refunds do not. Same collection identity and immutable facts is a no-op; changed facts conflict.

An authoritative zero ordinary booking total needs no collection report. It retains its zero external payable identity and obeys approval/fulfillment policy. A zero-total Tour instead has its separately documented no-Payment policy.

Read money and admission separately

External checkout collections page actual sources; do not count payable face value and its child allocations as separate income. Partial collections accumulate against the canonical payable. Late money does not revive a terminal booking.

An inline report can contain a complete ordinary booking selection. If a booking race prevents admission after collection facts are accepted, the durable report can exist without a confirmed booking. Read the report: underfunded, applied, action_required and requires_reconciliation have different next actions. Amount/payment can be null where no authoritative amount remains. Use the explicit resolution operation over real facts; do not repeat the original booking attempt or invent a refund.

External payable failed/void outcomes report actual outcomes with a retained outcome identity. They are not refunds.

Refund an actual collection

First inspect the cancellation plan and original collection sources. Request an external refund with payment, collection, retained refund ID, amount/currency and the frozen cancellation_refund_item_id when resolving a plan item. A pending request reserves capacity; it does not mean money was returned.

The studio executes the refund outside Podyx, then reports the actual outcome as succeeded, failed or reversed. Read the current refund, payable and plan. Successful/reversed outcomes affect actual claims once. A replacement attempt names replaces_refund_id and retains the root intention; a new HTTP UUID is not a new refund intention.

Permissions, effects and uncertainty

Native collection and external reporting have different permissions and readiness prerequisites, in addition to the relevant client/session authority. Submission can create durable checkout/report/refund identities and asynchronous provider work. Keep payment, staff approval, fulfillment, notification processing and delivery as separate facts.

Follow same-intent recovery. An undetermined provider result must retain its frozen provider request identity; another tender is unsafe. Do not infer rollback from an HTTP error or transport failure.