Payments & Deposits

This section covers the payments side of Hostme: deposits and prepayments for reservations (payment intents, secrets, payment statuses, refunds), plus service endpoints for the restaurant’s own payment cards, pricing plans and subscription.

All endpoints require a Bearer token (see Authentication) and live under the base path /api/core/payment. Payment operations on reservations are directly tied to BookingContract fields: depositToken, depositStatus, paymentType, intentClientSecret, paymentLinkUrl, details.paymentLinkUrl — see Reservations.

Deposits and prepayments for reservations

If the restaurant has prepayments or deposits configured, the reservation (BookingContract) gains payment fields. They are populated when the reservation is created/processed and updated as the payment progresses:

The depositToken field is passed when creating a reservation and ties the prepayment to the booking. Track the subsequent status in depositStatus and details.paymentError.

Create a payment intent

POST /restaurants/{restaurantId}/intents

Creates a payment intent and returns the secret the guest uses to confirm the payment on their side (in the payment widget). Used when taking a deposit/prepayment.

Response — IntentSecretContract

curl -X POST https://api.hostmeapp.com/api/core/payment/restaurants/123/intents \
  -H "Authorization: Bearer $TOKEN"

The returned secret matches the intentClientSecret field in BookingContract and is used by the guest-facing frontend to complete the payment.

Refund a deposit

POST /restaurants/{restaurantId}/reservations/{reservationId}/refund

Refunds the deposit (in full or in part) for a specific reservation. The refund amount is set in the request body; the response is the updated reservation.

Body — PaymentRefundContract

curl -X POST https://api.hostmeapp.com/api/core/payment/restaurants/123/reservations/RID/refund \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 25.00 }'

Response. The updated reservation (BookingContract) is returned — check the depositStatus, receiptAmount and details.paymentError fields to confirm the refund succeeded. For the full BookingContract structure, see Reservations.

Restaurant payment cards

Cards are used to pay for the restaurant’s own subscription and service charges.

List cards

GET /restaurants/{restaurantId}/cards

Returns an array of PaymentCard cards.

curl https://api.hostmeapp.com/api/core/payment/restaurants/123/cards \
  -H "Authorization: Bearer $TOKEN"

Attach a card

POST /restaurants/{restaurantId}/cards

Body — TokenContract: tokenized card data.

curl -X POST https://api.hostmeapp.com/api/core/payment/restaurants/123/cards \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "value": "tok_ABC_ID", "email": "owner@example.com", "fullName": "John Parker" }'

Default card

PUT /restaurants/{restaurantId}/cards/{cardId}

Makes the specified card the default.

Remove a card

DELETE /restaurants/{restaurantId}/cards/{cardId}

Detaches the card from the restaurant.

Charge history

GET /restaurants/{restaurantId}/charges

Returns a paginated list of charges.

curl -G https://api.hostmeapp.com/api/core/payment/restaurants/123/charges \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "skip=0" \
  --data-urlencode "take=20"

The exact schema of the successful response (200) is not fixed in the specification — the charge structure is returned by the payment system.

Pricing plans and restaurant subscription

This group of endpoints manages the restaurant’s own Hostme subscription (plans, sign-up, cancellation). Most partner integrations do not need it.

List plans

GET /restaurants/{restaurantId}/plans

Returns an array of PaymentPlanContract.

curl https://api.hostmeapp.com/api/core/payment/restaurants/123/plans \
  -H "Authorization: Bearer $TOKEN"

Plan by ID

GET /restaurants/{restaurantId}/plans/{planId}

Returns a single plan by identifier (planId — path).

Email a plan

POST /restaurants/{restaurantId}/plans/{planId}/email

Body — PaymentPlanMailContract: { "email": "..." }. Sends the plan description to the given address.

Subscribe

POST /restaurants/{restaurantId}/subscriptions

Body — PaymentCreateSubscriptionContract.

curl -X POST https://api.hostmeapp.com/api/core/payment/restaurants/123/subscriptions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "planId": "plan_ABC_ID", "fullName": "John Parker", "email": "owner@example.com" }'

Current subscriptions

GET /restaurants/{restaurantId}/subscriptions

Returns the restaurant’s subscriptions.

Subscription usage

GET /restaurants/{restaurantId}/subscription/usage

Returns usage data within the subscription (quotas, consumption).

Cancel a subscription

DELETE /restaurants/{restaurantId}/subscriptions/{subscriptionId}

Body — CancelationReasonContract.

Cancellation feedback

POST /restaurants/{restaurantId}/subscriptions/{subscriptionId}/feedback

Body — CancelationFeedbackContract: experience, customExperienceMessage. Collects feedback after a subscription is cancelled.

Payment reminder

POST /restaurants/{restaurantId}/remind

Sends a reminder that the subscription payment is due.

Miscellaneous

• POST /restaurants/{restaurantId}/accounts — create a payment account (body — TokenContract: value, email, fullName).
• GET /restaurants/{restaurantId}/customer — the restaurant’s payer details.
• DELETE /restaurants/{restaurantId}/customer — delete the payer.

The POST /payment/events and POST /payment/events/{appId} endpoints are service webhooks of the payment system; partner integrations do not call them directly.

General request rules and error codes are in Conventions and Errors. Payment fields within a reservation are described in Reservations.