Set the cart payment method
Sets the payment method on the cart (idempotent). The request and response
shapes vary by payment type. The declared contract requires type; the
saved-payment-method flow (payment_method_id) is the only flow that may
omit payment_method. The saved-payment-method flow also requires a
customer/user JWT (body jwt, Authorization header, or session) and
fails with 422 without one. Returns 400 when a type-specific
required key is absent.
While a redirect payment (PPRO, dLocal, Citcon) is open at the provider,
the switch first voids that charge at the provider. It goes ahead once a
status read confirms the charge can no longer be paid, and answers 409
(meta.code = payment_in_progress) while it may still be paid.
curl --request PUT \
--url https://api.fluid.app/api/payments/v2026-04/carts/{cart_token}/payment_method \
--header 'Content-Type: application/json' \
--data '
{
"type": "credit_card",
"payment_method": {
"vgs_card_id": "card_9f8e7d6c"
},
"billing_address": {
"name": "Ada Lovelace",
"address1": "1 Analytical Way",
"city": "London",
"state": "LDN",
"postal_code": "EC1A 1BB",
"country_code": "GB"
}
}
'{
"card": {
"id": 88123,
"brand": "visa",
"last_four": "4242",
"exp_month": 12,
"exp_year": 2030
}
}Headers
Optional non-authorizing checkout journey UUID. Use with X-Checkout-Attempt-Id. Capture is disabled by default; malformed or incomplete pairs are ignored without changing checkout behavior. Cart scope comes from the authenticated cart token, never these headers.
Optional customer-submission UUID paired with X-Checkout-Journey-Id. Retain it for transport retries and originating continuations; use a new UUID for a new customer submission. It does not replace payment or order idempotency keys. Invalid pairs are ignored rather than rejecting payment.
Path Parameters
Opaque cart token returned by the create-cart response. It scopes the request to a single cart and is the credential for these endpoints — cart-token authentication carried in the path, with no bearer token or API key.
Body
Payment type (credit_card, paypal, apple_pay, klarna, bread, affirm, ach, or a platform type such as *_citcon, *_ppro, *_dlocal).
Type-specific payment payload (e.g. VGS card fields for credit_card; order_id/token for paypal; authorization_token/session_id for klarna). For credit_card, token_provider defaults to vgs and is matched case-insensitively; any other value is a 422.
Show child attributes
Show child attributes
Optional billing address. All fields are optional.
Show child attributes
Show child attributes
PaymentAccount UUID override for routing.
Integration-specific customer details.
Show child attributes
Show child attributes
Braintree Data Collector fraud fingerprint.
Resolve payment_method_id against the customer's saved payment methods instead of the shared wallet.
Existing saved PaymentMethod id (saved payment method flow).
Customer/user JWT authorizing use of a saved payment method (may also be sent as an Authorization header).
Raw Apple Pay payment token envelope (apple_pay flow).
Show child attributes
Show child attributes
VGS-decrypted Apple Pay token data (apple_pay flow, inbound VGS route).
Show child attributes
Show child attributes
Secondary payment-type selector. When set to "paypal" on an apple_pay request, routes the decrypted Apple Pay token through the PayPal-on-Apple-Pay flow.
Response
Payment method set
Success body for setting the cart payment method. The shape varies by payment type: credit_card/apple_pay return card; saved payment methods return card + payment_method; paypal returns order_id (Braintree SDK PayPal also returns transaction_id); klarna returns authorization_token; ach returns the same ach session as ach_session; bread/affirm/platform payments return an empty object.
PayPal order id (paypal and decrypted Apple Pay-on-PayPal flows).
Braintree transaction id (Braintree SDK PayPal flow).
Klarna authorization token (klarna flow).
The ACH session. Routing has chosen the account behind it, and the checkout mounts that provider's collector from this object alone. The payment-method list carries no provider credentials.
Show child attributes
Show child attributes
Sanitized stored-card JSON (credit_card, apple_pay, and saved payment method flows).
Show child attributes
Show child attributes
Formatted payment method (saved payment method flow).
Show child attributes
Show child attributes
curl --request PUT \
--url https://api.fluid.app/api/payments/v2026-04/carts/{cart_token}/payment_method \
--header 'Content-Type: application/json' \
--data '
{
"type": "credit_card",
"payment_method": {
"vgs_card_id": "card_9f8e7d6c"
},
"billing_address": {
"name": "Ada Lovelace",
"address1": "1 Analytical Way",
"city": "London",
"state": "LDN",
"postal_code": "EC1A 1BB",
"country_code": "GB"
}
}
'{
"card": {
"id": 88123,
"brand": "visa",
"last_four": "4242",
"exp_month": 12,
"exp_year": 2030
}
}