Create a payout | MVS Developer Docs

Creates a Hyperswitch payout for the authenticated organization via the engine SDK (POST /v1/payouts) and upserts a settlementExtension sidecar keyed by the returned payout_id with approvalStatus: "PENDING" (the MVS platform approval gate before funds move). Pass an Idempotency-Key header to make retries safe; a deterministic one (mvspay_<orgId>_<uuid>) is generated server-side if omitted. Unknown body fields are forwarded verbatim to the engine. Returns 201 with the created payout and its sidecar; a payout created without a payout_id cannot be persisted and yields a 502.

Creates a Hyperswitch payout for the authenticated organization via the engine SDK (`POST /v1/payouts`) and upserts a `settlementExtension` sidecar keyed by the returned `payout_id` with `approvalStatus: "PENDING"` (the MVS platform approval gate before funds move). Pass an `Idempotency-Key` header to make retries safe; a deterministic one (`mvspay_<orgId>_<uuid>`) is generated server-side if omitted. Unknown body fields are forwarded verbatim to the engine. Returns **201** with the created payout and its sidecar; a payout created without a `payout_id` cannot be persisted and yields a 502.

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).

currencystringRequired

customer_idstringOptional

payout_method_datamap from strings to anyOptional

Tokenized / saved payout-method data forwarded to the engine.

auto_fulfillbooleanOptional

Fulfill the payout immediately after confirmation.

confirmbooleanOptional

Confirm the payout on creation.

descriptionstringOptional

metadatamap from strings to anyOptional

Response

The created payout and its persisted settlement-extension sidecar.

payoutobject

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

extensionobject

Org-scoped sidecar persisted alongside the Hyperswitch payout. Carries the MVS platform approval workflow (the gate before payout funds move).

Errors

401

Unauthorized Error

403

Forbidden Error

500

Internal Server Error

502

Bad Gateway Error

$	curl -X POST https://pay.mvscloud.com/api/payouts \
>	-H "x-api-key: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"amount": 50000,
>	"currency": "USD",
>	"customer_id": "cus_acme_001",
>	"auto_fulfill": false,
>	"confirm": false,
>	"description": "Weekly merchant settlement",
>	"metadata": {
>	"settlement_period": "2026-W25"
>	}
>	}'

1	{
2	"payout": {
3	"payout_id": "payout_Rk3sample789",
4	"status": "requires_confirmation",
5	"amount": 50000,
6	"currency": "USD"
7	},
8	"extension": {
9	"id": "stx_01",
10	"organizationId": "org_acme",
11	"hyperswitchPayoutId": "payout_Rk3sample789",
12	"approvalStatus": "PENDING",
13	"createdAt": "2026-06-21T12:00:00.000Z",
14	"updatedAt": "2026-06-21T12:00:00.000Z"
15	}
16	}

Authentication

Headers

Request

Response

Errors