Save a tokenized payment method for a customer

Saves a payment method for the customer from a one-time token. The customer must already have a linked Hyperswitch customer identity (otherwise 404). The request is routed to the engine’s /v1/customers/{id}/payment-methods extension path; the response is the engine payment-method object (loosely typed; extra fields pass through). Pass an Idempotency-Key header to make retries safe.

Saves a payment method for the customer from a one-time `token`. The customer must already have a linked Hyperswitch customer identity (otherwise 404). The request is routed to the engine's `/v1/customers/{id}/payment-methods` extension path; the response is the engine payment-method object (loosely typed; extra fields pass through). Pass an `Idempotency-Key` header to make retries safe.

Authentication

x-api-keystring

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

Path parameters

idstringRequired

The org-scoped billing customer id.

Request

This endpoint expects an object.

tokenstringRequired

One-time token representing the card to save.

tagsmap from strings to anyOptional

Optional free-form tags forwarded to the engine.

Response

The saved payment method as returned by the engine.

payment_method_idstring

brandstring or null

last4string or null

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

500

Internal Server Error

502

Bad Gateway Error

$	curl -X POST https://pay.mvscloud.com/api/customers/id/payment-methods \
>	-H "x-api-key: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"token": "tok_save_card_abc123",
>	"tags": {
>	"label": "Primary card"
>	}
>	}'