PaymentsPreview

Preview. Native payments are on the roadmap for a later phase and are not live yet. This page documents the intended shape so you can plan ahead. Fields and behavior may change before general availability. Today Coastly operates record-only: orders and reservations are captured, and settlement happens off-platform per the vendor's own arrangements.

What is coming

Owner-managed payments let a property or vendor connect their own Stripe Connect account so guests can pay natively during a Coastly booking or order, with funds settling directly to the owner. Coastly orchestrates the charge and records the result; the owner remains the merchant of record on their connected account.

Planned model

• Onboarding. Owners connect a Stripe account from the vendor dashboard. Until an account is connected, endpoints that would move money return 402 gateway_not_connected.
• Charges. When a reservation or order is created against a payments-enabled vendor, Coastly initiates the charge on the owner's connected account.
• Payouts. Funds settle to the owner's Stripe balance on their payout schedule. Coastly's commission is handled as an application fee.
• Refunds. Cancellations and modifications can trigger full or partial refunds through the same connected account.

Planned webhook events

Payment lifecycle events will be delivered through the existing webhooks channel, signed the same way. Expect events in the payment.* family (for example payment.succeeded, payment.refunded) alongside the current reservation, order, and invoice events.

The gateway_not_connected error

You can already handle the not-connected case today. Any action that requires a payment gateway when none is connected returns:

{
  "error": {
    "code": "gateway_not_connected",
    "message": "This vendor has not connected a payment gateway.",
    "request_id": "req_8Kd2p1"
  }
}

Treat this as a prompt to have the owner complete payment onboarding, then retry.

Building now

Until native payments ship, keep your integration record-only: create reservations and orders through the API, read invoices and commission, and reconcile settlement out of band. When payments go live, the same resources gain payment state without breaking existing fields.