Documentation
Pyncht prices every charge you take, line by line, and marks the fees that are avoidable. REST over HTTPS, JSON in and out, idempotent writes, and official libraries for Node, Python, Ruby, Go, and PHP.
Filters the documentation index below as you type.
Quickstart
About four minutes against a test key. Test keys read and write test data only — nothing on this page can move real money.
Install the library
Node 18 or later. TypeScript definitions ship inside the package, so there is no separate @types install.
npm install pyncht
Authenticate
One client per process. maxNetworkRetries re-sends with the same idempotency key, so a retried create never charges twice.
const pyncht = require('pyncht')(process.env.PYNCHT_SECRET_KEY, {
apiVersion: '2026-07-14',
maxNetworkRetries: 2,
});
module.exports = pyncht;Make your first request
Create a charge, expand its fee lines, and read what the charge actually cost you. Every line is a fee somebody genuinely bills.
const charge = await pyncht.charges.create({
amount: 4200, // smallest currency unit
currency: 'usd',
source: 'tok_visa',
description: 'Invoice 8841',
expand: ['fee_lines'],
});
// Every charge carries its own itemised cost.
for (const line of charge.fee_lines) {
console.log(`${line.category}: ${line.amount_cents}c`);
}
// interchange: 69c · scheme: 6c · markup: 19c · fixed: 10cInstall the library
Python 3.9 or later. Pure Python with no compiled extensions, so it installs anywhere a wheel is not available.
python -m pip install pyncht
Authenticate
One client per process. max_network_retries re-sends with the same idempotency key, so a retried create never charges twice.
import os
import pyncht
client = pyncht.Client(
api_key=os.environ["PYNCHT_SECRET_KEY"],
api_version="2026-07-14",
max_network_retries=2,
)Make your first request
Create a charge, expand its fee lines, and read what the charge actually cost you. Every line is a fee somebody genuinely bills.
charge = client.charges.create(
amount=4200, # smallest currency unit
currency="usd",
source="tok_visa",
description="Invoice 8841",
expand=["fee_lines"],
)
# Every charge carries its own itemised cost.
for line in charge.fee_lines:
print(f"{line.category}: {line.amount_cents}c")
# interchange: 69c · scheme: 6c · markup: 19c · fixed: 10cInstall the library
Ruby 3.0 or later. Add gem "pyncht" to your Gemfile if the app is bundled.
gem install pyncht
Authenticate
The Ruby library is configured at module level. Retries reuse the idempotency key, so a re-sent create never charges twice.
require "pyncht"
Pyncht.api_key = ENV.fetch("PYNCHT_SECRET_KEY")
Pyncht.api_version = "2026-07-14"
Pyncht.max_network_retries = 2Make your first request
Create a charge, expand its fee lines, and read what the charge actually cost you. Every line is a fee somebody genuinely bills.
charge = Pyncht::Charge.create(
amount: 4200, # smallest currency unit
currency: "usd",
source: "tok_visa",
description: "Invoice 8841",
expand: ["fee_lines"]
)
# Every charge carries its own itemised cost.
charge.fee_lines.each do |line|
puts "#{line.category}: #{line.amount_cents}c"
end
# interchange: 69c · scheme: 6c · markup: 19c · fixed: 10cInstall the library
Go 1.21 or later. The major version tracks the API surface, so /v2 is pinned to the 2026-07-14 release.
go get github.com/pyncht/pyncht-go/v2
Authenticate
A package-level client is fine — it is safe for concurrent use. Every write carries an idempotency key, so a retry never charges twice.
import (
"os"
pyncht "github.com/pyncht/pyncht-go/v2"
)
var client = pyncht.New(os.Getenv("PYNCHT_SECRET_KEY"),
pyncht.WithAPIVersion("2026-07-14"))Make your first request
Create a charge, expand its fee lines, and read what the charge actually cost you. Every line is a fee somebody genuinely bills.
charge, err := client.Charges.Create(ctx, &pyncht.ChargeParams{
Amount: pyncht.Int64(4200),
Currency: pyncht.String("usd"),
Source: pyncht.String("tok_visa"),
Description: pyncht.String("Invoice 8841"),
Expand: []*string{pyncht.String("fee_lines")},
})
if err != nil {
log.Fatal(err)
}
// Every charge carries its own itemised cost.
for _, line := range charge.FeeLines {
fmt.Printf("%s: %dc\n", line.Category, line.AmountCents)
}Install the library
PHP 8.1 or later. Autoloading is PSR-4, so Composer's autoloader is the whole bootstrap.
composer require pyncht/pyncht-php
Authenticate
One client per request cycle. Retries reuse the idempotency key, so a re-sent create never charges twice.
require_once 'vendor/autoload.php';
$pyncht = new \Pyncht\PynchtClient([
'api_key' => getenv('PYNCHT_SECRET_KEY'),
'api_version' => '2026-07-14',
'max_network_retries' => 2,
]);Make your first request
Create a charge, expand its fee lines, and read what the charge actually cost you. Every line is a fee somebody genuinely bills.
$charge = $pyncht->charges->create([
'amount' => 4200, // smallest currency unit
'currency' => 'usd',
'source' => 'tok_visa',
'description' => 'Invoice 8841',
'expand' => ['fee_lines'],
]);
// Every charge carries its own itemised cost.
foreach ($charge->fee_lines as $line) {
printf("%s: %dc\n", $line->category, $line->amount_cents);
}
// interchange: 69c · scheme: 6c · markup: 19c · fixed: 10cThe four fee lines above are the real breakdown of a $42.00 US Visa credit charge: 165 bps interchange, 14 bps scheme, 45 bps markup and a 10c fixed fee — 104c in total, or 248 bps. Full API reference
Reference
Nothing in the documentation index matches . There are only six pages here — try api, cli, webhook, typescript or oauth.
API objects
Eight resources carry the whole product. Six of them look like any payments API.
The last two — fee_lines and
opportunities — are the ones Pyncht exists for.
Bodies below are from the sample analysis that powers the demo dashboard: an illustrative merchant on $269,269 a month, not a customer.
{
"id": "ch_3QwZ8kR2P1a4Kd",
"object": "charge",
"amount": 4200,
"currency": "usd",
"captured": true,
"network": "visa",
"funding": "credit",
"customer": "cus_QkP2m4Rd81",
"description": "Invoice 8841",
"cost_cents": 104,
"effective_rate_bps": 248,
"fee_lines": ["fl_9dT2", "fl_9dT3", "fl_9dT4", "fl_9dT5"],
"opportunities": ["opp_network_tokens"],
"created": 1785283200
}cost_cents is the sum of the charge's four fee lines. 104c on a $42.00 charge is 248 bps, against a 249 bps blended rate for this account.
{
"id": "cus_QkP2m4Rd81",
"object": "customer",
"name": "Northwind Supply",
"email": "ap@northwind-supply.test",
"default_payment_method": "pm_1NvR8qKd",
"account_updater": {
"enrolled": true,
"last_refreshed": 1784592000
},
"charges_30d": 6,
"volume_30d_cents": 113376,
"cost_30d_cents": 2823,
"created": 1712880000
}volume_30d_cents divided by charges_30d gives the $188.96 average ticket this account runs. account_updater.enrolled is why its expired-card declines stay low.
{
"id": "sub_1QxA7mR2P1",
"object": "subscription",
"customer": "cus_QkP2m4Rd81",
"status": "active",
"interval": "month",
"amount": 18896,
"currency": "usd",
"network_token": true,
"retry_policy": "issuer_aware",
"next_attempt": 1787961600,
"recovered_cents_90d": 18896,
"created": 1751328000
}retry_policy: "issuer_aware" schedules retries against the decline reason rather than a fixed cadence. Expired cards and issuer timeouts recover above 88%; do not honour recovers at 34%.
{
"id": "in_1QxB4nR2P1",
"object": "invoice",
"number": "NWS-8841",
"customer": "cus_QkP2m4Rd81",
"status": "paid",
"subtotal": 4200,
"tax": 0,
"total": 4200,
"charge": "ch_3QwZ8kR2P1a4Kd",
"processing_cost_cents": 104,
"net_cents": 4096,
"created": 1785196800
}net_cents is total minus processing_cost_cents — the figure your ledger should book, computed at capture rather than reconstructed at month end.
{
"id": "po_1QxC9pR2P1",
"object": "payout",
"status": "paid",
"currency": "usd",
"gross_cents": 26926900,
"fees_cents": 670995,
"amount": 26255905,
"charge_count": 1425,
"period": {
"start": 1782864000,
"end": 1785456000
},
"arrival_date": 1785542400,
"reconciliation": "matched"
}One month of the sample account: $269,269 gross across 1,425 charges, $6,709.95 of fees, $262,559.05 settled. reconciliation: "matched" means every fee line in the period rolls up to this payout with no residual.
{
"id": "dp_1QxD2sR2P1",
"object": "dispute",
"charge": "ch_3QwZ8kR2P1a4Kd",
"amount": 4200,
"reason": "product_not_received",
"status": "warning_needs_response",
"fee_cents": 1500,
"alert": {
"network": "ethoca",
"received_at": 1785312000,
"deflectable": true
},
"evidence_due_by": 1786089600
}alert.deflectable marks the disputes an Ethoca or RDR alert can resolve before they post. The sample account takes about 6 chargebacks a month at $15 each, plus the lost sale.
{
"id": "fl_9dT2",
"object": "fee_line",
"charge": "ch_3QwZ8kR2P1a4Kd",
"category": "interchange",
"amount_cents": 69,
"payable_to": "issuer",
"basis": {
"volume_cents": 4200,
"rate_bps": 165,
"fixed_cents": 0,
"card_class": "visa_credit"
},
"avoidable": true,
"opportunity": "opp_network_tokens"
}The three sibling lines on this charge: scheme 6c, markup 19c, fixed 10c. Categories are interchange, scheme, markup, fixed, cross_border, fx and chargeback. avoidable is only ever true when an opportunity can actually remove it.
{
"id": "opp_network_tokens",
"object": "opportunity",
"title": "Enable network tokens on recurring cards",
"kind": "fee_reduction",
"effort": "low",
"confidence": 0.86,
"monthly_cents": 13442,
"annual_cents": 161303,
"basis": {
"volume_cents": 11201590,
"rate_delta_bps": 12,
"charges": 593
},
"status": "open"
}monthly_cents is basis.volume_cents × basis.rate_delta_bps and nothing else: $112,015.90 of recurring credit volume across 593 charges, 12 bps cheaper when tokenised, $134.42 a month. Nothing is asserted here without the arithmetic that produced it.