Charge a custom amount to a saved card
curl --request POST \
--url https://billing.funnelfox.com/{org_id}/v1/payment/one_off_charge \
--header 'Content-Type: application/json' \
--header 'ff-secret-key: <api-key>' \
--data '
{
"external_id": "<string>",
"amount": 123,
"currency_code": "<string>",
"idempotency_key": "<string>",
"client_metadata": {}
}
'import requests
url = "https://billing.funnelfox.com/{org_id}/v1/payment/one_off_charge"
payload = {
"external_id": "<string>",
"amount": 123,
"currency_code": "<string>",
"idempotency_key": "<string>",
"client_metadata": {}
}
headers = {
"ff-secret-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'ff-secret-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
external_id: '<string>',
amount: 123,
currency_code: '<string>',
idempotency_key: '<string>',
client_metadata: {}
})
};
fetch('https://billing.funnelfox.com/{org_id}/v1/payment/one_off_charge', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://billing.funnelfox.com/{org_id}/v1/payment/one_off_charge",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'external_id' => '<string>',
'amount' => 123,
'currency_code' => '<string>',
'idempotency_key' => '<string>',
'client_metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"ff-secret-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://billing.funnelfox.com/{org_id}/v1/payment/one_off_charge"
payload := strings.NewReader("{\n \"external_id\": \"<string>\",\n \"amount\": 123,\n \"currency_code\": \"<string>\",\n \"idempotency_key\": \"<string>\",\n \"client_metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("ff-secret-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://billing.funnelfox.com/{org_id}/v1/payment/one_off_charge")
.header("ff-secret-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"external_id\": \"<string>\",\n \"amount\": 123,\n \"currency_code\": \"<string>\",\n \"idempotency_key\": \"<string>\",\n \"client_metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://billing.funnelfox.com/{org_id}/v1/payment/one_off_charge")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["ff-secret-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"external_id\": \"<string>\",\n \"amount\": 123,\n \"currency_code\": \"<string>\",\n \"idempotency_key\": \"<string>\",\n \"client_metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"action_required_token": "<string>",
"checkout_status": "processing",
"failed_message_for_user": "<string>",
"order_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"idempotent_replay": false
}Payment management
Charge a custom amount to a saved card
Charge an arbitrary amount and currency against a customer’s saved card, without a Price Point.
POST
/
payment
/
one_off_charge
Charge a custom amount to a saved card
curl --request POST \
--url https://billing.funnelfox.com/{org_id}/v1/payment/one_off_charge \
--header 'Content-Type: application/json' \
--header 'ff-secret-key: <api-key>' \
--data '
{
"external_id": "<string>",
"amount": 123,
"currency_code": "<string>",
"idempotency_key": "<string>",
"client_metadata": {}
}
'import requests
url = "https://billing.funnelfox.com/{org_id}/v1/payment/one_off_charge"
payload = {
"external_id": "<string>",
"amount": 123,
"currency_code": "<string>",
"idempotency_key": "<string>",
"client_metadata": {}
}
headers = {
"ff-secret-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'ff-secret-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
external_id: '<string>',
amount: 123,
currency_code: '<string>',
idempotency_key: '<string>',
client_metadata: {}
})
};
fetch('https://billing.funnelfox.com/{org_id}/v1/payment/one_off_charge', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://billing.funnelfox.com/{org_id}/v1/payment/one_off_charge",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'external_id' => '<string>',
'amount' => 123,
'currency_code' => '<string>',
'idempotency_key' => '<string>',
'client_metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"ff-secret-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://billing.funnelfox.com/{org_id}/v1/payment/one_off_charge"
payload := strings.NewReader("{\n \"external_id\": \"<string>\",\n \"amount\": 123,\n \"currency_code\": \"<string>\",\n \"idempotency_key\": \"<string>\",\n \"client_metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("ff-secret-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://billing.funnelfox.com/{org_id}/v1/payment/one_off_charge")
.header("ff-secret-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"external_id\": \"<string>\",\n \"amount\": 123,\n \"currency_code\": \"<string>\",\n \"idempotency_key\": \"<string>\",\n \"client_metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://billing.funnelfox.com/{org_id}/v1/payment/one_off_charge")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["ff-secret-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"external_id\": \"<string>\",\n \"amount\": 123,\n \"currency_code\": \"<string>\",\n \"idempotency_key\": \"<string>\",\n \"client_metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"action_required_token": "<string>",
"checkout_status": "processing",
"failed_message_for_user": "<string>",
"order_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"idempotent_replay": false
}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 returnone_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, unique per customer, and shared with POST /checkout/one_click.
- Same key, same amount and currency: Nothing is charged again. The original outcome is returned with
idempotent_replay: trueand the originalorder_id. - Same key, different amount or currency: The request is rejected with
idempotency_key_reused. Nothing is charged. - Key already used for a one-click payment: Rejected with
idempotency_key_reused. - New key: A new charge, even for the same amount.
What the customer receives
Each successful charge grants one consumable. No subscription or one-off purchase is created, so the charge appears inPOST /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.
If the PSP no longer accepts the saved card, the response is HTTP 200 with checkout_status: failed and a failed_message_for_user asking for new card details. Nothing is charged, and retries with the same key also return failed.Authorizations
Body
application/json
Response
200 - application/json
Payment status and details
Was this page helpful?
