Skip to main content
POST
Charge a saved card into a card-acquiring merchant

Authorizations

Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

Request body for POST /v1/platform/payments/card-to-merchant.

The card is identified by payment_method_id (a card already vaulted for a user under the tenant). card_acquiring_id selects the NMI merchant (MID) the funds deposit into; it must match the merchant the card was vaulted under (vault tokens are MID-namespaced). Omit it to use the tenant's first approved card-acquiring account.

payment_method_id
string<uuid>
required

Public id of the saved card to charge.

payer_user_id
string<uuid>
required

Public id of the payer (cardholder) user being charged.

amount
required

Amount to hold, major units.

Required range: x > 0
idempotency_key
string
required

Caller-chosen unique key; a replay returns the same record.

Required string length: 1 - 120
card_acquiring_id
string<uuid> | null

Public id of the card-acquiring merchant to deposit into. Optional — when omitted the tenant's first approved (oldest created) card-acquiring account is used. When supplied it is always honoured; there is no fallback, and a card vaulted under a different account is refused.

destination_wallet_id
string<uuid> | null

Public id of the exact wallet to credit. Optional — when omitted the funds land in the card-acquiring account owner's primary wallet for the currency. The wallet must belong to this tenant and its currency must match currency; it does not have to be a primary wallet. Not accepted when the card-acquiring account settles to an external bank account.

currency
string
default:USD
Required string length: 3
metadata
Metadata · object | null

Optional caller metadata stored on the record.

Response

Successful Response

Standard response wrapper for single-object responses and errors.

Generic over the payload type. A route that declares CommonResponse[SomeModel] gets the real data schema rendered in OpenAPI/Swagger; a bare CommonResponse leaves data untyped.

status_code
integer
required

HTTP status code for the response.

data
any
required

Payload or error details.

query_generated_time
integer
required

UTC timestamp (milliseconds since epoch) when response was generated.