Payments

Payment methods are tokenized cards held in a PCI-DSS-compliant vault. Movmo stores id, last4, brand, expMonth, expYear, and isDefault; the full PAN and the vault token never leave Movmo’s server. Tokenization happens client-side in the Movmo accounts UI via Hosted Fields, keeping partners (and Movmo) in PCI DSS SAQ A scope.

Payment model

Movmo is a booking facilitator, not a payment processor. The vault holds the traveler’s card and forwards it to the airline’s PSP on Movmo’s behalf at booking time — Movmo never authorizes, captures, or charges the card.

• Merchant of record: the airline’s PSP, never Movmo.
• 3DS / SCA: owned by the airline’s PSP. The PSP authenticates the cardholder and settles the charge; Movmo only vaults and forwards.

This is a vault + Receiver-forwarding architecture: a partner integration that worked under any prior payment model continues to work, because the partner contract only ever exposes the Movmo payment method UUID.

Common patterns

• The full PAN is not in Movmo. Card capture happens in the Movmo-hosted tokenization surface; partners never receive or forward the PAN.
• 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 is best-effort against the vault. The server attempts to redact the vault token, then deletes the local row regardless of the vault result so the UI removes the card immediately. A 204 means the card is gone from the partner-visible surface — orphaned vault tokens are reconciled out-of-band.

Integration timing

Saved payment methods work end-to-end today. Follow one rule at booking time:

Read payment_method_id from GET /v1/users/{userid}/payment-methods at booking time; do not cache it between requests, and pass it through to POST .../bookings unchanged.

The UUID is stable: when Movmo switches vault or receiver configurations server-side, the same payment_method_id keeps resolving to the same card. Partner code needs no changes across migrations.

REST endpoints

Operation	Path
listPaymentMethods	GET /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}

Card capture is fronted by the Movmo accounts UI and runs through POST /v1/users/{userid}/payment-methods/from-token, which exchanges a vault token (produced by Hosted Fields against the PCI vault) for a Movmo payment method UUID. It is documented in the OpenAPI spec for completeness, but is not part of the partner integration surface — partners read existing methods via listPaymentMethods and pass id as payment_method_id on bookings.

Partners who want to embed Movmo card capture directly in their own UI instead of redirecting users to the Movmo accounts UI can use the @movmo_app/payments React SDK, which wraps Hosted Fields and the from-token exchange into drop-in components.

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

Response shape

GET /v1/users/{userid}/payment-methods returns an array of objects with the following lean shape:

{
  "id": "33333333-3333-3333-3333-333333333333",
  "userId": "00000000-0000-0000-0000-000000000001",
  "methodType": "credit_card",
  "last4": "4242",
  "brand": "visa",
  "expMonth": 12,
  "expYear": 2027,
  "isDefault": true,
  "createdAt": "2026-05-01T12:00:00Z",
  "updatedAt": "2026-05-01T12:00:00Z"
}

The only field a partner needs at booking time is id — pass it as payment_method_id on POST .../bookings.

Model Context Protocol (MCP) tools

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 Movmo accounts UI for new cards.