MVS Pay APIPayments

Create a payment

Mints a Hyperswitch payment_intent and returns the `client_secret` the browser SDK confirms with the card. **Trust model (ADR-010):** the organization is resolved from a VERIFIED context, never the body. On a tenant host (`acme.mvspay.io`) the public checkout path is used with **no** API key; off a tenant host, the `x-api-key` path (`transactions:write`) applies. A `metadata.organization_id` that disagrees with the verified org is rejected (403). Public promotion of this endpoint is gated on the §6 anti-automation controls in the platform plan.

Authentication

x-api-keystring

A scoped MvsPayApiKey, e.g. mvspay_live_…. Mint and scope keys from the dashboard (Settings → API Keys).

Request

This endpoint expects an object.
amountintegerRequired

Minor units (cents).

currencystringRequiredDefaults to USD
confirmbooleanOptional

false → intent only (browser confirms); true → server confirm.

capture_methodenumOptional
customer_idstringOptional
descriptionstringOptional
payment_methodstringOptional

A saved payment-method id (saved-card flow).

payment_method_datamap from strings to anyOptional

Tokenized fresh-card data, e.g. { token }.

return_urlstringOptionalformat: "uri"
surcharge_amountintegerOptional
convenience_amountintegerOptional
tip_amountintegerOptional
healthcare_clinic_amountintegerOptional
invoice_reference_numberstringOptional
metadatamap from strings to anyOptional

A metadata.organization_id, if present, must match the verified tenant org.

Response

The created payment_intent (loosely typed; extra Hyperswitch fields pass through).

payment_idstring
statusstring

e.g. requires_payment_method, requires_confirmation, succeeded, processing, cancelled.

amountinteger

Minor units (cents).

currencystring
client_secretstring
Mounted by the browser SDK to confirm with the card.
merchant_idstring
connectorstring

Connector chosen by Hyperswitch (may be null).

metadatamap from strings to any

Includes server-stamped mvs_org_id / mvs_org_slug.

Errors

400
Bad Request Error
403
Forbidden Error
404
Not Found Error
502
Bad Gateway Error