Skip to content

Perform a one-click purchase

POST
/checkout/one_click
billing.funnelfox.com

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 same action_required_token for up to 1 hour, then processing with 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.

org_id
required
string

Organization ID

Media typeapplication/json
OneClick
object
external_id
required
Customer Id

Your unique identifier for the user

string
≤ 256 characters
pp_ident
required
price point ident

Unique identifier of the price point

string
≤ 256 characters · /^[-A-Za-z_0-9]{1,256}$/
client_metadata
object
Client Metadata

Custom metadata from your client application

Show 1 propertyHide property
key
additional properties
any
initiation_type
Initiation Type

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.

string
nullable
one of cit mit
cit_card_networks
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.

Array<string>
nullable
one of AMEX CARTES_BANCAIRES DINERS_CLUB DISCOVER EFTPOS ELO JCB MAESTRO MASTERCARD MIR UNIONPAY VISA
idempotency_key
Idempotency Key

Unique key per purchase attempt. Reuse it on every retry of that attempt so the customer is charged only once.

string
nullable · 1–128 characters
payment_method_token
Payment Method Token

Wallet confirmation: the token from the Apple Pay or Google Pay sheet the customer confirmed. Send it with session_id.

string
nullable · 1–512 characters · /^[A-Za-z0-9_-]+$/
session_id
Session Id

Wallet confirmation: session_id from POST /checkout/one_click_wallet_session. Send it with payment_method_token.

string format: uuid
nullable

200 Payment status and details

Section titled “200”
Media typeapplication/json
OneClickCheckoutOut
object
action_required_token
required
Action Required Token
string
checkout_status
required
CheckoutPaymentStatus
string
one of processing succeeded failed cancelled
failed_message_for_user
required
Failed Message For User
string
decline_code
Decline Code
string
nullable
decline_code_source
Any of:
IntegrationEnum
string
one of fakeintegration primer stripe
order_id
required
string format: uuid
nullable
idempotent_replay
Idempotent Replay

True when this response replays an earlier one-click request made with the same idempotency key, rather than a new charge.

boolean