curl --request POST \
--url https://api.openloophealth.com/v0.1/billing-customers/{provider_customer_id}/balance-transactions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"amount": 300,
"currency": "usd",
"description": "Referral refunded",
"metadata": {
"provider_invoice_id": "test_invoice_id"
}
}
'import requests
url = "https://api.openloophealth.com/v0.1/billing-customers/{provider_customer_id}/balance-transactions"
payload = {
"amount": 300,
"currency": "usd",
"description": "Referral refunded",
"metadata": { "provider_invoice_id": "test_invoice_id" }
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
amount: 300,
currency: 'usd',
description: 'Referral refunded',
metadata: {provider_invoice_id: 'test_invoice_id'}
})
};
fetch('https://api.openloophealth.com/v0.1/billing-customers/{provider_customer_id}/balance-transactions', 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://api.openloophealth.com/v0.1/billing-customers/{provider_customer_id}/balance-transactions",
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([
'amount' => 300,
'currency' => 'usd',
'description' => 'Referral refunded',
'metadata' => [
'provider_invoice_id' => 'test_invoice_id'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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://api.openloophealth.com/v0.1/billing-customers/{provider_customer_id}/balance-transactions"
payload := strings.NewReader("{\n \"amount\": 300,\n \"currency\": \"usd\",\n \"description\": \"Referral refunded\",\n \"metadata\": {\n \"provider_invoice_id\": \"test_invoice_id\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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://api.openloophealth.com/v0.1/billing-customers/{provider_customer_id}/balance-transactions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 300,\n \"currency\": \"usd\",\n \"description\": \"Referral refunded\",\n \"metadata\": {\n \"provider_invoice_id\": \"test_invoice_id\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.openloophealth.com/v0.1/billing-customers/{provider_customer_id}/balance-transactions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": 300,\n \"currency\": \"usd\",\n \"description\": \"Referral refunded\",\n \"metadata\": {\n \"provider_invoice_id\": \"test_invoice_id\"\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"provider_balance_transaction_id": "test_balance_transaction_id",
"provider_customer_id": "test_customer_id",
"amount": 300,
"currency": "usd",
"description": "Referral refunded",
"ending_balance": -200,
"type": "adjustment",
"provider_invoice_id": null,
"created": 1300,
"metadata": {
"provider_invoice_id": "test_invoice_id"
}
}
}Create Balance Transaction
Grants account credit to one of your billing customers, or claws unused credit back. amount uses the payment provider’s sign, the same convention as the billing customer’s balance: a negative amount grants credit (at most 10000, $100.00 in USD, per request), and a positive amount claws credit back (at most the remaining credit, so the balance never goes above 0). The grant itself is not invoiced: the credit appears on the invoice it pays, and description / metadata record why it was granted. The part of an invoice paid with credit is refunded back to the balance, not to the card, with balance_amount on POST /invoices/{provider_invoice_id}/refunds. Concurrent clawbacks for the same customer are not serialized.
Retrying a clawback. The remaining-credit check runs against the live balance before the request reaches the payment provider, so retrying a clawback that already succeeded, even with the same Idempotency-Key, can return 400 because the credit it took is already gone. Before retrying a clawback that may have succeeded, check GET /billing-customers/{provider_customer_id}/balance-transactions for it. A same-key retry of a credit is deduplicated.
curl --request POST \
--url https://api.openloophealth.com/v0.1/billing-customers/{provider_customer_id}/balance-transactions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"amount": 300,
"currency": "usd",
"description": "Referral refunded",
"metadata": {
"provider_invoice_id": "test_invoice_id"
}
}
'import requests
url = "https://api.openloophealth.com/v0.1/billing-customers/{provider_customer_id}/balance-transactions"
payload = {
"amount": 300,
"currency": "usd",
"description": "Referral refunded",
"metadata": { "provider_invoice_id": "test_invoice_id" }
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
amount: 300,
currency: 'usd',
description: 'Referral refunded',
metadata: {provider_invoice_id: 'test_invoice_id'}
})
};
fetch('https://api.openloophealth.com/v0.1/billing-customers/{provider_customer_id}/balance-transactions', 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://api.openloophealth.com/v0.1/billing-customers/{provider_customer_id}/balance-transactions",
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([
'amount' => 300,
'currency' => 'usd',
'description' => 'Referral refunded',
'metadata' => [
'provider_invoice_id' => 'test_invoice_id'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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://api.openloophealth.com/v0.1/billing-customers/{provider_customer_id}/balance-transactions"
payload := strings.NewReader("{\n \"amount\": 300,\n \"currency\": \"usd\",\n \"description\": \"Referral refunded\",\n \"metadata\": {\n \"provider_invoice_id\": \"test_invoice_id\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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://api.openloophealth.com/v0.1/billing-customers/{provider_customer_id}/balance-transactions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 300,\n \"currency\": \"usd\",\n \"description\": \"Referral refunded\",\n \"metadata\": {\n \"provider_invoice_id\": \"test_invoice_id\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.openloophealth.com/v0.1/billing-customers/{provider_customer_id}/balance-transactions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": 300,\n \"currency\": \"usd\",\n \"description\": \"Referral refunded\",\n \"metadata\": {\n \"provider_invoice_id\": \"test_invoice_id\"\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"provider_balance_transaction_id": "test_balance_transaction_id",
"provider_customer_id": "test_customer_id",
"amount": 300,
"currency": "usd",
"description": "Referral refunded",
"ending_balance": -200,
"type": "adjustment",
"provider_invoice_id": null,
"created": 1300,
"metadata": {
"provider_invoice_id": "test_invoice_id"
}
}
}Authorizations
Headers
Deduplicates retried requests with the same key and parameters (about a 24-hour window), except a clawback retried after it succeeded, which can return 400. Printable ASCII with no trailing whitespace. Keep it short (a UUID works): the key is scoped to the customer before it reaches the payment provider, and a key too long once scoped is a 400. Without a key a retry is not deduplicated and grants the credit twice, so send one on every request.

