Skip to main content
POST
Charge a custom amount to a saved card
Charges any amount you specify against the customer’s saved card, without creating a Price Point. Use it for credit top-ups, token packs, and other consumable purchases whose price isn’t known in advance. This endpoint is server-side only and the amount comes straight from your request, so never call it from a browser or mobile app.

Availability

Custom charges are disabled by default. Contact FunnelFox to enable them for your organization. Calls to a disabled organization return one_off_charge_disabled.

Requirements

The customer must already have a successful payment with a saved card. The card, payment provider, region, and merchant account are all reused from that payment, so the currencies you can charge depend on that merchant account.

Idempotency

idempotency_key is required and must be unique per customer.
  • Same key, same amount and currency: Nothing is charged again. The original outcome is returned with idempotent_replay: true and the original order_id.
  • Same key, different amount or currency: The request is rejected with idempotency_key_reused. Nothing is charged.
  • New key: A new charge, even for the same amount.
Generate one key per purchase intent and reuse it for every retry of that intent. Generating a fresh key on retry will charge the customer twice.

What the customer receives

Each successful charge grants one consumable. No subscription or one-off purchase is created, so the charge appears in POST /my_assets under consumables only. A full refund of the order revokes the consumable; a partial or soft refund does not. No tax is calculated on custom charges.

Errors

All failures return HTTP 400. one_off_charge_disabled and idempotency_key_reused carry a machine-readable code; other failures are message-only: non-positive amount, unknown currency, too many decimal places for the currency, amount over your configured maximum, unknown customer, no prior successful payment, no saved card, or another charge already in progress for the customer.

Authorizations

ff-secret-key
string
header
required

Secret key for FunnelFox Billing API. Required for all requests.

Path Parameters

org_id
string
required

Organization ID

Body

application/json
external_id
string
required

Your unique identifier for the user

Maximum string length: 256
amount
required

Amount to charge. Must be greater than 0, must not have more decimal places than the currency allows, and must not exceed the maximum configured for your organization.

currency_code
string
required

Three-letter ISO currency code. Case-insensitive.

Required string length: 3
idempotency_key
string
required

Unique key per purchase intent. Reuse it on retries to avoid double-charging.

Required string length: 1 - 128
client_metadata
Client Metadata · object

Custom metadata from your client application

Response

200 - application/json

Payment status and details

action_required_token
string
required

Always empty for custom charges — merchant-initiated charges have no authentication step.

checkout_status
enum<string>
required
Available options:
processing,
succeeded,
failed,
cancelled
failed_message_for_user
string
required
order_id
string<uuid> | null
required
idempotent_replay
boolean
default:false

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