Create a payment | MVS Developer Docs

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.

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

Allowed values:

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_secretstringOptional

Mounted by the browser SDK to confirm with the card.

merchant_idstringOptional

connectorstringOptional

Connector chosen by Hyperswitch (may be null).

metadatamap from strings to anyOptional

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