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
payment_category
integer | null

Optional. The payment category code to tag this payment with, recording what the payment was for. Omit it and the payment is created exactly as before, untagged. If you do send one it must be a code your platform can currently use, otherwise the request is rejected and no money moves. Fetch the codes from GET /v1/platform/catalog/payment-categories. Codes are issued separately in test and live, so read the list in each mode — the same number does not mean the same category across them.

Required range: x > 0
Example:

1

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.

splits
CardToMerchantSplitCreate · object[] | null

Credit more than one wallet from this single charge. Between 1 and 10 legs; the leg amounts must add up exactly to amount; each wallet may appear at most once. Mutually exclusive with destination_wallet_id, and refused when the card-acquiring account settles to an external bank. Omit for the ordinary single-destination charge. Every leg lands in its wallet's pending balance while the payment awaits review and becomes spendable together on approval.

Required array length: 1 - 10 elements

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.