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.
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, 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).
Optional billing address. All fields are optional.
PaymentAccount UUID override for routing.
Integration-specific customer details.
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).
VGS-decrypted Apple Pay token data (apple_pay flow, inbound VGS route).
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; 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).
Sanitized stored-card JSON (credit_card, apple_pay, and saved payment method flows).
Formatted payment method (saved payment method flow).