Payments

Payment methods are tokenized cards. Movmo stores last4, brand, expiration, and the paymentMethodId token; the full PAN never reaches Movmo infrastructure. Tokenization happens client-side via Stripe Elements today; a Spreedly migration is planned.

Common patterns

• The full PAN is not in Movmo. Card capture must happen in a PCI-compliant tokenization surface before the token is POSTed to Movmo.
• Update is intentionally narrow. PUT accepts only expMonth, expYear, isDefault; other fields are ignored. Replacing a card means delete + create.
• isDefault is mutually exclusive across a user’s cards — setting one to true unsets the others atomically.
• Delete detaches at the provider first. A 5xx leaves the local row intact to avoid orphaning a charge token.

REST endpoints

Operation	Path
listPaymentMethods	GET /v1/users/{userid}/payment-methods
createPaymentMethod	POST /v1/users/{userid}/payment-methods
getPaymentMethod	GET /v1/users/{userid}/payment-methods/{methodid}
updatePaymentMethod	PUT /v1/users/{userid}/payment-methods/{methodid}
deletePaymentMethod	DELETE /v1/users/{userid}/payment-methods/{methodid}

Full schemas in the OpenAPI spec under tags: [Payments].

MCP tools

Model Context Protocol (MCP) wrappers for this domain:

Tool	Maps to
get_payment_methods	GET /v1/users/{userid}/payment-methods
delete_payment_method	GET + DELETE /v1/users/{userid}/payment-methods/{methodid}

Card addition is not exposed over MCP — adding a card requires a tokenization surface that an LLM has no business holding. The delete_payment_method tool’s confirmation message redirects users to the accounts UI for new cards.

Should I integrate now or wait for Spreedly?

Integrate now. Saved payment methods work end-to-end today. The Spreedly migration is a server-side abstraction; the partner contract holds, provided you follow one rule: read customer_id from GET /v1/users/{userid}/payment-methods at booking time, never persist it. Pass the freshly-read id and customer_id into POST .../bookings. When Spreedly lands, customer_id will be re-pointed server-side; partners that read-at-booking need no code changes.

Watch out for

• The internal payment-customer endpoints (GET/POST /v1/users/{userid}/payment-customer) leak the underlying provider concept and are deliberately omitted from the partner surface. Do not depend on them.