Create a card-not-present (keyed) sale

Processes a keyed / card-not-present sale as a confirmed payment_intent. Supply either a one-time token (fresh keyed card) or a saved paymentInstrumentId. Pass idempotencyId to make retries safe; one is generated server-side if omitted.

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>=50

Minor units (cents); minimum 50 ($0.50).

currencystringOptionalDefaults to USD

tokenstringOptional

One-time token for a freshly keyed card.

paymentInstrumentIdstringOptional

A saved payment-method id.

customerIdstringOptional

customerNamestringOptional

descriptionstringOptional

invoiceReferencestringOptional

tagsmap from strings to anyOptional

merchantIdstringOptional

Override the resolved merchant.

locationIdstringOptional

idempotencyIdstringOptional

Client-supplied idempotency id; generated server-side if omitted.

Response

The confirmed sale.

successboolean

paymentobject

Hyperswitch payment_intent response. Loosely typed; extra Hyperswitch fields pass through.

Errors

400

Bad Request Error

401

Unauthorized Error

500

Internal Server Error

502

Bad Gateway Error

$	curl -X POST https://pay.mvscloud.com/api/virtual-terminal \
>	-H "x-api-key: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"amount": 5000,
>	"currency": "USD",
>	"token": "tok_keyed_abc123",
>	"customerName": "Jane Roe",
>	"invoiceReference": "1042",
>	"idempotencyId": "mvspay_org_acme_1719000000_ab12cd34ef"
>	}'

1	{
2	"success": true,
3	"payment": {
4	"payment_id": "string",
5	"status": "string",
6	"amount": 1,
7	"currency": "string",
8	"client_secret": "string",
9	"merchant_id": "string",
10	"connector": "string",
11	"metadata": {}
12	}
13	}