Stripe Desktop API Guide
Use Stripe from a merchant’s billing or accounting application. This guide follows a customer from the local account record to an invoice, then shows how to refund a payment, reconcile a bank deposit, and create a shareable payment link.
The examples use an unlocked Chilkat 11.7.0 or later. Each HttpCurl call runs one explicit cURL command. The application reads the response and supplies any ID needed by the next request.
From cURL to HttpCurl
Suppose the operator wants to invoice Acme for the first time. Start by creating its Stripe Customer. The two snippets send the same form fields to the same endpoint. The C# snippet assumes the application has already loaded apiKey and operationId.
cURL in a shell
curl -X POST https://api.stripe.com/v1/customers \
-u "$STRIPE_API_KEY:" \
-H "Stripe-Version: 2026-10-28.endive" \
-H "Idempotency-Key: $OPERATION_ID-customer" \
--data-urlencode "name=Acme & Sons" \
--data-urlencode "email=billing+east@example.com" \
-d "metadata[account_ref]=ACME-1042"
The same request in C#
// apiKey comes from merchant-controlled configuration.
// operationId is the saved UUID for this customer creation.
var name = new Chilkat.StringBuilder();
name.SetString("Acme & Sons");
var email = new Chilkat.StringBuilder();
email.SetString("billing+east@example.com");
var cmd = new Chilkat.StringBuilder();
cmd.SetString("curl -X POST https://api.stripe.com/v1/customers");
cmd.Append(" -u \"@KEY@:\"");
cmd.Append(" -H \"Stripe-Version: 2026-10-28.endive\"");
cmd.Append(" -H \"Idempotency-Key: @OP@-customer\"");
cmd.Append(" -d \"name=@NAME@\"");
cmd.Append(" -d \"email=@EMAIL@\"");
cmd.Append(" -d \"metadata[account_ref]=ACME-1042\"");
cmd.Replace("@NAME@", name.GetEncoded("url_rfc3986", "utf-8"));
cmd.Replace("@EMAIL@", email.GetEncoded("url_rfc3986", "utf-8"));
cmd.Replace("@OP@", operationId);
cmd.Replace("@KEY@", apiKey);
var curl = new Chilkat.HttpCurl();
if (!curl.DoYourThing(cmd.GetAsString())) {
Console.WriteLine("No HTTP response. Failure code: " + curl.FailReason);
return;
}
var json = new Chilkat.JsonObject();
bool hasJson = curl.GetResponseJson(json);
if (curl.StatusCode != 200 || !hasJson) {
Console.WriteLine("HTTP " + curl.StatusCode + " Request-Id: "
+ curl.GetResponseHeaderField("Request-Id"));
if (hasJson) Console.WriteLine(json.StringOf("error.message"));
return;
}
string customerId = json.StringOf("id");
// Save customerId on the billing record for ACME-1042.
- Authentication and headers
- HttpCurl reads
-u,-H, the method, and the URL directly from the command string. The colon after the key supplies an empty Basic Auth password. The shell expands$STRIPE_API_KEY. In C#, the application inserts the key before callingDoYourThing. Use a restricted sandbox key for testing. Keep merchant credentials in trusted configuration and keep authenticated commands out of logs. A desktop client distributed to customers sends privileged requests through the merchant’s backend. Stripe key handling - Form fields and query parameters
- The shell uses
--data-urlencodefor free text. The C# example encodes each value before passing it with-d. An ampersand stays part of the business name, and a literal plus stays part of the email address. For a filtered GET, the examples put the encoded filter in the URL. List requests usehas_moreand pass the last returned ID asstarting_afterfor the next page. - Responses and retries
- A true return from
DoYourThingmeans an HTTP response arrived. Check its status and parse the JSON before using the ID. If the connection drops after a write, retry the same operation with its saved idempotency key and identical parameters. Give each distinct write its own key, including creating a draft and adding its first line. Stripe idempotent requests
Customers
A billing clerk already knows Acme as ACME-1042. When linking that account for the first time, save the returned Stripe Customer ID on the billing record and send the local reference in metadata[account_ref]. For a customer already in Stripe, an email lookup can return several records. Show the matches and their references before the clerk chooses which record to link.
Subscriptions
Choose an active recurring price by its catalog lookup key, then create an invoice-billed subscription for the saved customer. To change a plan or seat count, identify the subscription item (si_...), preview the proration, and carry the accepted item, price, quantity, and proration timestamp into the update. Read the invoice to determine whether payment arrived.
Invoices
Create a draft with auto_advance=false so the clerk can review it. Read invoiceId = json.StringOf("id") from the response to POST /v1/invoices. In the next command, pass that value as the invoice field to POST /v1/invoiceitems, together with the customer and price. Omitting the invoice field can leave a pending item for a later invoice. Finalize the reviewed draft, then send the open invoice. Stripe test mode returns the send result without delivering email.
Refunds
Start with the paid invoice in the billing system. List its payment allocations and select the charge or PaymentIntent for the payment being refunded. Specify the amount in the currency’s minor units for a partial refund, or omit it to refund the remaining refundable amount. Save the returned refund ID so the clerk can check a pending or failed refund later.
Balances and Reconciliation
For a balance inquiry, display all available and pending amounts by currency. For the ledger, page through balance transactions for a UTC date range and export their gross, fee, and net amounts. To investigate a bank deposit, select a completed automatic payout, retrieve its settlement transactions across all pages, and compare their net total with the payout in the same currency.
Payment Links
Create a Payment Link for a catalog price and quantity. Give the customer the returned url and save the plink_... ID for the operator who manages the link. A recurring price sells a subscription. Deactivating the link closes it to new purchases while existing subscriptions continue on their own terms.