> ## Documentation Index
> Fetch the complete documentation index at: https://funnelfox.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Charge a custom amount to a saved card

> Charge an arbitrary amount and currency against a customer's saved card, without a Price Point.

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](https://funnelfox.com/docs/billing/consumables). No subscription or one-off purchase is created, so the charge appears in [`POST /my_assets`](https://funnelfox.com/docs/api-reference/information/list-a-users-subscriptions-and-one-off-purchases) 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.


## OpenAPI

````yaml /swagger/openapi-billing.json post /payment/one_off_charge
openapi: 3.0.0
info:
  title: OpenAPI3
  version: 1.0.0
servers:
  - url: https://billing.funnelfox.com/{org_id}/v1
    description: FunnelFox Billing API
    variables:
      org_id:
        default: your-org-id
        description: Your organization ID
security:
  - FunnelFoxSecretKey: []
paths:
  /payment/one_off_charge:
    post:
      tags:
        - Payment management
      summary: Charge a custom amount to a saved card
      description: >-
        Charge an arbitrary amount and currency against a customer's saved card,
        without a Price Point.
      parameters:
        - name: org_id
          in: path
          required: true
          description: Organization ID
          schema:
            type: string
          style: simple
          explode: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OneOffChargeIn'
      responses:
        '200':
          description: Payment status and details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OneOffChargeOut'
components:
  schemas:
    OneOffChargeIn:
      properties:
        external_id:
          description: Your unique identifier for the user
          maxLength: 256
          title: Customer Id
          type: string
        amount:
          anyOf:
            - type: number
            - type: string
          description: >-
            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.
          title: Amount
        currency_code:
          description: Three-letter ISO currency code. Case-insensitive.
          maxLength: 3
          minLength: 3
          title: Currency Code
          type: string
        idempotency_key:
          description: >-
            Unique key per purchase intent. Reuse it on retries to avoid
            double-charging.
          maxLength: 128
          minLength: 1
          title: Idempotency Key
          type: string
        client_metadata:
          additionalProperties: true
          description: Custom metadata from your client application
          title: Client Metadata
          type: object
      required:
        - external_id
        - amount
        - currency_code
        - idempotency_key
      title: OneOffChargeIn
      type: object
    OneOffChargeOut:
      properties:
        action_required_token:
          description: >-
            Always empty for custom charges — merchant-initiated charges have no
            authentication step.
          title: Action Required Token
          type: string
        checkout_status:
          $ref: '#/components/schemas/CheckoutPaymentStatus'
        failed_message_for_user:
          title: Failed Message For User
          type: string
        order_id:
          format: uuid
          type: string
          nullable: true
        idempotent_replay:
          default: false
          description: >-
            True when this response replays an earlier charge made with the same
            idempotency key, rather than a new charge.
          title: Idempotent Replay
          type: boolean
      required:
        - action_required_token
        - checkout_status
        - failed_message_for_user
        - order_id
      title: OneOffChargeOut
      type: object
    CheckoutPaymentStatus:
      enum:
        - processing
        - succeeded
        - failed
        - cancelled
      title: CheckoutPaymentStatus
      type: string
  securitySchemes:
    FunnelFoxSecretKey:
      type: apiKey
      in: header
      name: ff-secret-key
      description: Secret key for FunnelFox Billing API. Required for all requests.

````