Money contract and 1.0 migration
The 1.0 contract is a breaking change: upgrade API consumers, checkout forms, SDKs and integrations together. Use Node.js/Go 1.0.0, PHP/Java/.NET/Ruby/Elixir 1.0.1, and Python/Rust 1.0.2. Native integration versions and installation channels are listed in the SDK catalog. Numeric money is not accepted alongside the string contract.
Monetary request, response and webhook fields contain canonical base-10 integer strings in the currency's minor unit. Existing field names remain: root payment amount, basket price, balances, premiums, fees, settlement amounts and fields ending in Minor all follow this rule. Rates, percentages, basis points, quantities, counts and timestamps keep their existing types.
{
"amount": "9007199254740993",
"currency": "TRY",
"basketItems": [
{ "id": "item-1", "name": "Example", "itemType": "PHYSICAL", "price": "9007199254740993" }
]
}This is an exactness fixture, not a claim that a provider accepts that transaction size. Product, provider and existing storage limits still apply.
| Domain | Canonical spelling |
|---|---|
| Positive payment / capture / refund | "1", "10050" |
| Nonnegative totals where zero is permitted | "0", "10050" |
| Signed balances and differences | "-10050", "0", "10050" |
JSON numbers are rejected, even when small. Decimal text, whitespace, a leading plus, leading zeroes, "-0", exponent notation, NaN and Infinity are invalid. Fiat signed-64 storage spans "-9223372036854775808" through "9223372036854775807"; each field still enforces its own sign and bounds. Crypto domains may use larger precision and are not globally capped at 19 digits.
For optional capture/refund amounts, omit the field to use the eligible remaining amount. Explicit "0" and JSON null are invalid monetary request values. Use the SDK’s documented argument omission or dedicated remaining-amount operation (for example, PHP captureRemaining / refundRemaining); do not pass null to a required string argument. This preserves the existing operation and idempotency key.
Convert from decimal text
Use the actual supported currency exponent. Do not infer TRY from a missing currency, multiply a floating-point input by 100, or parse a response amount with Number, parseFloat or an equivalent float conversion.
| Currency | Exponent | Decimal text input | Minor string |
|---|---|---|---|
| JPY | 0 | "1500" | "1500" |
| TRY | 2 | "15.00" | "1500" |
| KWD | 3 | "1.500" | "1500" |
Convert digit text directly with an exact integer/decimal library. Keep arithmetic in bigint or an equivalent exact type, then serialize with .toString(). A bigint itself is not a JSON value. Store imported spreadsheet amounts as text to preserve digits before conversion. Aggregate money only within the same currency.
Upgrade checklist
- Update persisted order snapshots, request types and response readers to strings; retain approved totals and original currency.
- Update all payment methods, split legs, refunds, captures, fixed fees, payout/settlement, wallet, links, subscriptions, insurance and Physical POS consumers.
- Sign the exact new JSON body. Verify webhook signatures over the original raw bytes before parsing. Do not rewrite amounts before signature verification.
- Retain merchant/environment ownership, idempotency keys and stored attempt bodies. An uncertain old attempt must be reconciled; changing its body or generating a new key is not an upgrade strategy.
- Test
"9007199254740993", JPY/TRY/KWD, signed balances, numeric rejection and omitted-versus-zero refund/capture. Test the provider's actual technical bounds separately.
The public API has no numeric compatibility path. Internal historical event/config decoders are narrowly scoped to known unversioned persisted records and safe integer values; they are not available for new public input. Never repair an already rounded unsafe number by converting it to text.
Analytics that expose monetary totals require an explicit currency or separate per-currency groups. Backtest uploads use major decimal text with one explicit supported currency per file; normalized transactions and report money use minor strings. Numeric spreadsheet money cells are rejected.
Physical POS
Physical POS uses the same string contract for amountMinor, item prices and taxes, reversal totals, report totals and end-of-day amounts. Update the SDK request models and raw HTTP bodies together. quantityMilli, counts, rateBp and rowVersion remain numbers; unavailable response amounts can remain null where documented.
Operation rules still apply: amount-based REFUND and PREAUTH_CLOSE require a positive amount string. For an itemized refund, omit the optional total or line amount to let the server derive it; explicit null is rejected. VOID and PREAUTH_CANCEL omit the amount and use their defined full amount. See Physical POS payments and item refunds.