Perform a one-click purchase
Initiate a one-click purchase for a given Price Point using the user’s saved payment method.
The payment goes as merchant-initiated (MIT) by default. It goes as customer-initiated (CIT) when one-click settings, initiation_type, or cit_card_networks ask for it and the saved method is a card from a Primer integration. Saved Apple Pay, Google Pay, and PayPal methods, and payments made from the FunnelFox Payments dashboard, always go as MIT.
Wallet confirmation: For a customer who paid with Apple Pay or Google Pay, send payment_method_token and session_id from POST /checkout/one_click_wallet_session. The payment then goes as CIT, and initiation_type and cit_card_networks are ignored.
3DS: A CIT payment can need 3DS. A non-empty action_required_token means the payment is pending until the customer completes the challenge. Complete it with POST /checkout/resume_payment. Until then, another one-click request for the same customer returns an error, unless it reuses the same idempotency_key.
Idempotency: Send one idempotency_key per purchase attempt and reuse it on every retry. Keys are unique per customer and shared with POST /payment/one_off_charge.
- Same key, same Price Point: Charges nothing and returns the original order with
idempotent_replay: true. An open 3DS challenge returns the sameaction_required_tokenfor up to 1 hour, thenprocessingwith an empty token. - Same key, different Price Point or a custom charge: Returns
idempotency_key_reused. - No key: Every request is a new charge.
- Original request created no payment: A retry 10 minutes or more after it returns
failed.
Errors: These return HTTP 400 with a code, and nothing is charged:
idempotency_key_reused: The key belongs to a different purchase.idempotency_key_in_progress: Another request for this customer is running. Retry with the same key.saved_payment_method_rejected: The saved payment method is no longer valid. Ask the customer for new card details.wallet_session_invalid: The wallet session expired or doesn’t match this purchase. Prepare a new one.wallet_token_rejected: The wallet payment couldn’t be completed. Prepare a new wallet session and try again.
Rate limit: One-click requests are limited per saved payment method by one_click_limit (default: 5 per hour). Exceeding it returns HTTP 429.
Parameters
Section titled “Parameters”Organization ID
Request bodyrequired
Section titled “Request Bodyrequired”object
Your unique identifier for the user
Unique identifier of the price point
Custom metadata from your client application
Show 1 propertyHide property
How to send the payment: cit (customer-initiated) or mit (merchant-initiated). Leave it out to use the organization setting. Without the ff-secret-key header, this field can only make the setting stricter: mit is applied, cit is ignored where the setting is mit, or cit_by_button without cit_card_networks.
Card brands allowed to go as CIT. Leave it out or send an empty list to allow all brands. A non-empty list limits CIT to those brands. Where the setting is cit_by_button, a non-empty list turns CIT on for those brands.
Unique key per purchase attempt. Reuse it on every retry of that attempt so the customer is charged only once.
Wallet confirmation: the token from the Apple Pay or Google Pay sheet the customer confirmed. Send it with session_id.
Wallet confirmation: session_id from POST /checkout/one_click_wallet_session. Send it with payment_method_token.
Responses
Section titled “Responses”200 Payment status and details
Section titled “200”object
True when this response replays an earlier one-click request made with the same idempotency key, rather than a new charge.