curl --request POST \
--url https://api.openloophealth.com/v0.1/invoices/{provider_invoice_id}/refunds \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"amount": 19900,
"balance_amount": 2000,
"reason": "duplicate",
"description": "Refunded duplicate charge"
}
'import requests
url = "https://api.openloophealth.com/v0.1/invoices/{provider_invoice_id}/refunds"
payload = {
"amount": 19900,
"balance_amount": 2000,
"reason": "duplicate",
"description": "Refunded duplicate charge"
}
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: 19900,
balance_amount: 2000,
reason: 'duplicate',
description: 'Refunded duplicate charge'
})
};
fetch('https://api.openloophealth.com/v0.1/invoices/{provider_invoice_id}/refunds', 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/invoices/{provider_invoice_id}/refunds",
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' => 19900,
'balance_amount' => 2000,
'reason' => 'duplicate',
'description' => 'Refunded duplicate charge'
]),
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/invoices/{provider_invoice_id}/refunds"
payload := strings.NewReader("{\n \"amount\": 19900,\n \"balance_amount\": 2000,\n \"reason\": \"duplicate\",\n \"description\": \"Refunded duplicate charge\"\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/invoices/{provider_invoice_id}/refunds")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 19900,\n \"balance_amount\": 2000,\n \"reason\": \"duplicate\",\n \"description\": \"Refunded duplicate charge\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.openloophealth.com/v0.1/invoices/{provider_invoice_id}/refunds")
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\": 19900,\n \"balance_amount\": 2000,\n \"reason\": \"duplicate\",\n \"description\": \"Refunded duplicate charge\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"provider_credit_note_id": "test_credit_note_id",
"provider_invoice_id": "test_invoice_id",
"status": "issued",
"amount": 19900,
"refund_amount": 17900,
"balance_amount": 2000,
"currency": "usd",
"reason": "duplicate",
"description": "Refunded duplicate charge",
"credit_note_pdf": "https://pay.stripe.com/credit_notes/abc/pdf",
"created": 1900
}
}Create Refund
Issues a refund against a paid invoice, recorded on one credit note. The card part of amount goes back to the invoice’s card payments; balance_amount, when sent, goes back to the billing customer’s credit balance instead.
Concurrency. Two refunds for the same invoice sent at the same time under different keys are not serialized: each checks the caps before the other writes, so together they can exceed the balance_amount cap. The payment provider’s own limit on the invoice total still bounds them.
curl --request POST \
--url https://api.openloophealth.com/v0.1/invoices/{provider_invoice_id}/refunds \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"amount": 19900,
"balance_amount": 2000,
"reason": "duplicate",
"description": "Refunded duplicate charge"
}
'import requests
url = "https://api.openloophealth.com/v0.1/invoices/{provider_invoice_id}/refunds"
payload = {
"amount": 19900,
"balance_amount": 2000,
"reason": "duplicate",
"description": "Refunded duplicate charge"
}
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: 19900,
balance_amount: 2000,
reason: 'duplicate',
description: 'Refunded duplicate charge'
})
};
fetch('https://api.openloophealth.com/v0.1/invoices/{provider_invoice_id}/refunds', 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/invoices/{provider_invoice_id}/refunds",
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' => 19900,
'balance_amount' => 2000,
'reason' => 'duplicate',
'description' => 'Refunded duplicate charge'
]),
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/invoices/{provider_invoice_id}/refunds"
payload := strings.NewReader("{\n \"amount\": 19900,\n \"balance_amount\": 2000,\n \"reason\": \"duplicate\",\n \"description\": \"Refunded duplicate charge\"\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/invoices/{provider_invoice_id}/refunds")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 19900,\n \"balance_amount\": 2000,\n \"reason\": \"duplicate\",\n \"description\": \"Refunded duplicate charge\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.openloophealth.com/v0.1/invoices/{provider_invoice_id}/refunds")
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\": 19900,\n \"balance_amount\": 2000,\n \"reason\": \"duplicate\",\n \"description\": \"Refunded duplicate charge\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"provider_credit_note_id": "test_credit_note_id",
"provider_invoice_id": "test_invoice_id",
"status": "issued",
"amount": 19900,
"refund_amount": 17900,
"balance_amount": 2000,
"currency": "usd",
"reason": "duplicate",
"description": "Refunded duplicate charge",
"credit_note_pdf": "https://pay.stripe.com/credit_notes/abc/pdf",
"created": 1900
}
}Authorizations
Headers
Deduplicates retried requests with the same key and parameters instead of creating a second resource (roughly a 24-hour replay window). Recommended: an opaque, randomly-generated value such as a UUID. A refund is created before the credit note that records it: if the call fails after a refund went through, retry with the same key — the payment provider replays that refund instead of creating a second one, and the retry links it on the credit note. That promise covers a failed credit note; retry a failed call within the 24-hour window, because after it the payment provider treats the retry as a new request and can refund again. On an invoice paid in more than one payment, if one payment's refund is rejected after another's went through, the retry replays the same rejection and the refund that went through stays unlinked: it is not counted against the refundable amount, so contact OpenLoop before retrying under a new key. A same-key retry of a call that already succeeded returns the original refund without refunding again — at any time with a key; the same key with a different amount, balance_amount or reason returns 400. Without a key the scope is derived from amount, balance_amount and reason, and an identical keyless request is treated as a retry of the first for 24 hours after it succeeded; after that it is a new refund — send an Idempotency-Key to issue two equal refunds sooner.
Body
Total refund in cents, card and balance together. Positive integer. Its card part (amount − balance_amount) is no greater than the invoice's card-refundable amount: what its paid card payments paid, minus the refunds already linked to credit notes on the invoice. A payment recorded outside the payment provider is not refundable to card.
Part of amount, in cents, returned to the billing customer's balance instead of the card. Integer from 0 to amount; absent means 0 (card only). No greater than the credit that was applied to the invoice from the balance, minus what earlier credit notes already returned to the balance — so only the credit-paid part goes back to the balance.

