From f9333ca30c1f77f2713418dd9d479aeaf25ae8fa Mon Sep 17 00:00:00 2001
From: Jakub Kasprzyk <kasprzykjakub@proton.me>
Date: Tue, 20 Oct 2026 10:34:36 +0200
Subject: [PATCH] fix: send exact decimal amounts to Apple Pay and Google Pay

- `PaymentItem.amount` is now `PaymentAmount` (`number | string`). iOS
  parses amounts with `NSDecimalNumber(string:)` instead of
  `Decimal(Double)`, so 19.99 reaches PassKit as 19.99, not
  19.98999999999999488. Android parses and sums them as `BigDecimal`.
  Numbers are read through their shortest round-trip form.
- New `normalizePaymentRequest`, used by `createPaymentRequest` and the
  hook's `startPayment`, rejects NaN, malformed strings, more decimals
  than the currency allows (ISO 4217) and a negative total before any
  native call, then sends amounts as decimal strings. Negative line
  items (discounts) stay allowed.
- `calculateTotal`, the hook's `total` and `formatAmount` use exact
  decimal arithmetic; `formatAmount` accepts strings and a currency.
- Native code rejects unparseable amounts and a negative total; Android
  also rejects a third decimal place instead of rounding.
- Docs, README, CHANGELOG and the example app use `formatAmount`.

Closes #18
---
 CHANGELOG.md                                  |  20 ++
 README.md                                     |  65 +++--
 docs/docs/api/hybrid-payment-handler.md       |  22 +-
 docs/docs/api/types.md                        |  23 +-
 docs/docs/api/use-payment-checkout.md         |  11 +-
 docs/docs/api/utils.md                        |  55 +++-
 docs/docs/guides/dynamic-cart.md              |  14 +-
 docs/docs/guides/manual-flow.md               |   2 +-
 docs/docs/quick-start.md                      |   3 +-
 example/app/(tabs)/index.tsx                  |   3 +-
 .../nitro/pay/GooglePayRequestBuilder.kt      |  27 +-
 .../com/margelo/nitro/pay/PaymentAmounts.kt   |  32 +++
 .../nitro/pay/GooglePayRequestBuilderTest.kt  |  72 ++++-
 .../margelo/nitro/pay/PaymentAmountsTest.kt   |  57 ++++
 package/ios/HybridPaymentHandler.swift        |  49 +++-
 package/ios/PaymentAmount+Decimal.swift       |  28 ++
 .../android/NitroPay+autolinking.cmake        |   1 +
 .../android/c++/JHybridPaymentHandlerSpec.cpp |   2 +
 .../generated/android/c++/JPaymentAmount.cpp  |  26 ++
 .../generated/android/c++/JPaymentAmount.hpp  |  68 +++++
 .../generated/android/c++/JPaymentItem.hpp    |  12 +-
 .../generated/android/c++/JPaymentRequest.hpp |   2 +
 .../com/margelo/nitro/pay/PaymentAmount.kt    |  62 +++++
 .../com/margelo/nitro/pay/PaymentItem.kt      |   4 +-
 .../ios/NitroPay-Swift-Cxx-Bridge.hpp         |  30 +++
 .../ios/NitroPay-Swift-Cxx-Umbrella.hpp       |   1 +
 .../ios/c++/HybridPaymentHandlerSpecSwift.hpp |   1 +
 .../generated/ios/swift/PaymentAmount.swift   |  30 +++
 .../generated/ios/swift/PaymentItem.swift     |  27 +-
 .../generated/shared/c++/PaymentItem.hpp      |  11 +-
 .../usePaymentCheckout.integration.test.ts    | 111 +++++++-
 package/src/hooks/usePaymentCheckout.ts       |  35 ++-
 package/src/types/Payment.ts                  |  11 +-
 package/src/utils/__tests__/amounts.test.ts   | 147 ++++++++++
 .../utils/__tests__/paymentHelpers.test.ts    |  49 +++-
 package/src/utils/amounts.ts                  | 250 ++++++++++++++++++
 package/src/utils/index.ts                    |   1 +
 package/src/utils/paymentHelpers.ts           |  65 +++--
 38 files changed, 1313 insertions(+), 116 deletions(-)
 create mode 100644 package/android/src/main/java/com/margelo/nitro/pay/PaymentAmounts.kt
 create mode 100644 package/android/src/test/java/com/margelo/nitro/pay/PaymentAmountsTest.kt
 create mode 100644 package/ios/PaymentAmount+Decimal.swift
 create mode 100644 package/nitrogen/generated/android/c++/JPaymentAmount.cpp
 create mode 100644 package/nitrogen/generated/android/c++/JPaymentAmount.hpp
 create mode 100644 package/nitrogen/generated/android/kotlin/com/margelo/nitro/pay/PaymentAmount.kt
 create mode 100644 package/nitrogen/generated/ios/swift/PaymentAmount.swift
 create mode 100644 package/src/utils/__tests__/amounts.test.ts
 create mode 100644 package/src/utils/amounts.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 88066c6..828282e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,8 +4,28 @@ All notable changes to this project are documented in this file.
 
 ## Unreleased
 
+### Changed
+
+- **Amounts can be decimal strings, and `PaymentItem.amount` is now `number | string`**
+  (`PaymentAmount`). Code that reads `item.amount` as a number no longer type-checks; display
+  amounts with `formatAmount(item.amount, currencyCode)`, which now accepts strings and an optional
+  currency code. Requests from `createPaymentRequest` hold their amount as a decimal string.
+- **Payments with invalid amounts no longer start.** `usePaymentCheckout().startPayment()` sets
+  `error` and returns `null`, and `createPaymentRequest` throws, when an amount is `NaN` or
+  infinite, has more decimal places than the currency allows (ISO 4217: `1.005` USD, `1200.5`
+  JPY, including float results such as `0.1 + 0.2`), or the total is negative. Negative line items
+  (discounts) are still allowed. For requests built by hand, call the new
+  `normalizePaymentRequest` before `HybridPaymentHandler.startPayment`.
+
 ### Fixed
 
+- **Amounts reach Apple Pay and Google Pay exactly.** iOS converted amounts with `Decimal(Double)`,
+  so `19.99` reached PassKit as `19.98999999999999488`. Amounts now cross into native code as
+  decimal strings, iOS parses them with `NSDecimalNumber` and Android with `BigDecimal`, and both
+  sum them exactly. `calculateTotal` and the hook's `total` use the same exact arithmetic. Google
+  Pay prices for zero-decimal currencies validated by `normalizePaymentRequest` are sent without
+  decimals (`"1500"` instead of `"1500.00"`), and Android rejects a negative total or a third
+  decimal place instead of rounding.
 - **Installing the package no longer runs `tsc` in your project.** 0.0.17 and earlier shipped a
   `postinstall` script (`tsc || exit 0`). The package does not include its own `tsconfig.json`, so
   `tsc` picked up the app's `tsconfig.json` and type-checked the whole app on every install; with a
diff --git a/README.md b/README.md
index 5b90856..6fba0f9 100644
--- a/README.md
+++ b/README.md
@@ -187,6 +187,7 @@ import {
   usePaymentCheckout,
   ApplePayButton,
   GooglePayButton,
+  formatAmount,
 } from '@gmisoftware/react-native-pay'
 import { Platform, View, Text, Button, ActivityIndicator } from 'react-native'
 
@@ -258,7 +259,7 @@ function CheckoutScreen() {
 
       {items.map((item, index) => (
         <View key={index} style={{ flexDirection: 'row', padding: 10 }}>
-          <Text>{item.label}: ${item.amount.toFixed(2)}</Text>
+          <Text>{item.label}: ${formatAmount(item.amount)}</Text>
           <Button title="Remove" onPress={() => removeItem(index)} />
         </View>
       ))}
@@ -386,8 +387,8 @@ interface UsePaymentCheckoutReturn {
 
   // Cart management
   items: PaymentItem[]; // Current cart items
-  total: number; // Total amount
-  addItem: (label: string, amount: number, type?: "final" | "pending") => void;
+  total: number; // Exact decimal total (NaN if an amount is invalid)
+  addItem: (label: string, amount: number | string, type?: "final" | "pending") => void;
   addItems: (items: Array<{ label; amount; type? }>) => void;
   removeItem: (index: number) => void;
   updateItem: (index: number, updates: Partial<PaymentItem>) => void;
@@ -463,14 +464,17 @@ interface PayServiceStatus {
 Start a payment request.
 
 ```typescript
-const result = await HybridPaymentHandler.startPayment({
-  countryCode: "US",
-  currencyCode: "USD",
-  merchantCapabilities: ["3DS"],
-  supportedNetworks: ["visa", "mastercard", "amex"],
-  paymentItems: [{ label: "Total", amount: 29.99, type: "final" }],
-  googlePayMerchantId: "your_google_pay_merchant_id",
-});
+const result = await HybridPaymentHandler.startPayment(
+  // Validates amounts before the sheet opens; see normalizePaymentRequest
+  normalizePaymentRequest({
+    countryCode: "US",
+    currencyCode: "USD",
+    merchantCapabilities: ["3DS"],
+    supportedNetworks: ["visa", "mastercard", "amex"],
+    paymentItems: [{ label: "Total", amount: "29.99", type: "final" }],
+    googlePayMerchantId: "your_google_pay_merchant_id",
+  })
+);
 ```
 
 **Options:**
@@ -617,6 +621,20 @@ const request = createPaymentRequest({
   googlePayGateway: "stripe",
   googlePayGatewayMerchantId: "your_merchant_id",
 });
+// request.paymentItems[0].amount === "29.99"
+```
+
+Throws if the amount is invalid for the currency (see [Amounts](#amounts)).
+
+#### `normalizePaymentRequest(request)`
+
+Validate every amount in a request you built yourself and convert it to an exact decimal string. `createPaymentRequest` and `usePaymentCheckout` call it for you.
+
+```typescript
+import { normalizePaymentRequest } from "@gmisoftware/react-native-pay";
+
+normalizePaymentRequest({ ...request, paymentItems: [{ label: "Book", amount: 19.9, type: "final" }] });
+// paymentItems: [{ label: 'Book', amount: '19.90', type: 'final' }]
 ```
 
 #### `createPaymentItem(label, amount, type)`
@@ -626,13 +644,13 @@ Create a payment item.
 ```typescript
 import { createPaymentItem } from "@gmisoftware/react-native-pay";
 
-const item = createPaymentItem("Subscription", 29.99, "final");
-// { label: 'Subscription', amount: 29.99, type: 'final' }
+const item = createPaymentItem("Subscription", "29.99", "final");
+// { label: 'Subscription', amount: '29.99', type: 'final' }
 ```
 
 #### `calculateTotal(items)`
 
-Calculate total from payment items.
+Calculate the exact decimal total of payment items.
 
 ```typescript
 import { calculateTotal } from "@gmisoftware/react-native-pay";
@@ -664,10 +682,13 @@ formatNetworkName("amex"); // "American Express"
 ### Core Types
 
 ```typescript
+// Amount in the currency's major unit: "19.99" or 19.99 (see Amounts below)
+type PaymentAmount = number | string;
+
 // Payment Item
 interface PaymentItem {
   label: string;
-  amount: number;
+  amount: PaymentAmount;
   type: "final" | "pending";
 }
 
@@ -733,6 +754,16 @@ type PaymentNetwork =
 type PaymentMethodType = "unknown" | "debit" | "credit" | "prepaid" | "store";
 ```
 
+### Amounts
+
+Amounts are numbers (`19.99`) or decimal strings (`"19.99"`) in the currency's major unit. Before a payment starts, the library validates them and sends them to native code as exact decimal strings (`NSDecimalNumber` on iOS, `BigDecimal` on Android), never through `Double`. The payment does not start when:
+
+- an amount is not a finite number or a plain decimal string (`NaN`, `"abc"`, `"1e3"`);
+- an amount has more decimal places than the currency allows (ISO 4217: `1.005` in USD, `"1200.5"` in JPY). This includes unrounded float results such as `0.1 + 0.2`; round them with `formatAmount(value, currencyCode)`;
+- the total is negative. Negative line items (discounts) are allowed.
+
+Google Pay accepts at most two decimal places, so three-decimal amounts (`"1.234"` KWD) fail on Android.
+
 ### Contact Types
 
 ```typescript
@@ -854,14 +885,14 @@ const handleAddToCart = (product) => {
 const handleUpdateQuantity = (index, quantity) => {
   const item = checkout.items[index];
   checkout.updateItem(index, {
-    amount: item.amount * quantity,
+    amount: formatAmount(Number(item.amount) * quantity),
   });
 };
 
 // Apply discount
 const handleApplyDiscount = (discountPercent) => {
   const discountAmount = checkout.total * (discountPercent / 100);
-  checkout.addItem("Discount", -discountAmount, "final");
+  checkout.addItem("Discount", formatAmount(-discountAmount), "final");
 };
 
 // Clear cart
diff --git a/docs/docs/api/hybrid-payment-handler.md b/docs/docs/api/hybrid-payment-handler.md
index da85c7d..96b1a41 100644
--- a/docs/docs/api/hybrid-payment-handler.md
+++ b/docs/docs/api/hybrid-payment-handler.md
@@ -28,15 +28,21 @@ const status = HybridPaymentHandler.payServiceStatus()
 
 Starts the native payment flow with the given request. Returns a promise that resolves with the payment result.
 
+Pass the request through `normalizePaymentRequest` (or build it with `createPaymentRequest`) so amounts are validated before the sheet opens. See [`PaymentAmount`](/docs/api/types#paymentamount).
+
 ```ts
-const result = await HybridPaymentHandler.startPayment({
-  countryCode: 'US',
-  currencyCode: 'USD',
-  merchantCapabilities: ['3DS'],
-  supportedNetworks: ['visa', 'mastercard', 'amex'],
-  paymentItems: [{ label: 'Total', amount: 29.99, type: 'final' }],
-  googlePayMerchantId: 'your_google_pay_merchant_id',
-})
+import { HybridPaymentHandler, normalizePaymentRequest } from '@gmisoftware/react-native-pay'
+
+const result = await HybridPaymentHandler.startPayment(
+  normalizePaymentRequest({
+    countryCode: 'US',
+    currencyCode: 'USD',
+    merchantCapabilities: ['3DS'],
+    supportedNetworks: ['visa', 'mastercard', 'amex'],
+    paymentItems: [{ label: 'Total', amount: '29.99', type: 'final' }],
+    googlePayMerchantId: 'your_google_pay_merchant_id',
+  })
+)
 // result: PaymentResult
 ```
 
diff --git a/docs/docs/api/types.md b/docs/docs/api/types.md
index 804adf1..8429e1c 100644
--- a/docs/docs/api/types.md
+++ b/docs/docs/api/types.md
@@ -2,6 +2,27 @@
 
 TypeScript types exported from `@gmisoftware/react-native-pay`. Use them for request/result handling and server integration.
 
+## PaymentAmount
+
+A monetary amount in the currency's major unit (dollars, not cents).
+
+```ts
+type PaymentAmount = number | string
+```
+
+- **Decimal string** (`'19.99'`): exact. Must match `^-?\d+(\.\d+)?$`; no exponents, spaces, or thousands separators.
+- **Number** (`19.99`): read as the shortest decimal that round-trips, so `19.99` stays exactly `19.99`. Results of float arithmetic such as `0.1 + 0.2` (`0.30000000000000004`) fail validation instead of being rounded.
+
+Before a payment starts, every amount is validated and sent to native code as a decimal string with the currency's number of decimal places (ISO 4217: 2 for USD, 0 for JPY, 3 for KWD). Native code converts it with `NSDecimalNumber` (iOS) and `BigDecimal` (Android), never through `Double`. A payment does not start when:
+
+- an amount is not a finite number or a plain decimal string (`NaN`, `Infinity`, `'abc'`);
+- an amount has more decimal places than the currency allows (`1.005` in USD, `'1200.5'` in JPY);
+- the total of `paymentItems` is negative. Negative line items (discounts) are allowed.
+
+Google Pay accepts at most two decimal places, so on Android a three-decimal amount such as `'1.234'` KWD fails with an error.
+
+---
+
 ## PaymentItem
 
 A single line item (label, amount, type).
@@ -9,7 +30,7 @@ A single line item (label, amount, type).
 ```ts
 interface PaymentItem {
   label: string
-  amount: number
+  amount: PaymentAmount // number | string
   type: 'final' | 'pending'
 }
 ```
diff --git a/docs/docs/api/use-payment-checkout.md b/docs/docs/api/use-payment-checkout.md
index bd49688..3580f23 100644
--- a/docs/docs/api/use-payment-checkout.md
+++ b/docs/docs/api/use-payment-checkout.md
@@ -46,8 +46,8 @@ interface UsePaymentCheckoutReturn {
   // Cart
   items: PaymentItem[]
   total: number
-  addItem: (label: string, amount: number, type?: 'final' | 'pending') => void
-  addItems: (items: Array<{ label: string; amount: number; type?: 'final' | 'pending' }>) => void
+  addItem: (label: string, amount: PaymentAmount, type?: 'final' | 'pending') => void
+  addItems: (items: Array<{ label: string; amount: PaymentAmount; type?: 'final' | 'pending' }>) => void
   removeItem: (index: number) => void
   updateItem: (index: number, updates: Partial<PaymentItem>) => void
   clearItems: () => void
@@ -67,9 +67,10 @@ interface UsePaymentCheckoutReturn {
 - **canMakePayments** — Whether the user can pay with Apple Pay / Google Pay on this device.
 - **canSetupCards** — Whether the user can add or manage cards (e.g. in Wallet).
 - **isCheckingStatus** — `true` while availability is being checked on mount.
-- **items** / **total** — Current cart and computed total.
+- **items** / **total** — Current cart and its exact decimal total, as a number (`NaN` if an amount is invalid). Amounts are `number | string` ([`PaymentAmount`](/docs/api/types#paymentamount)); use `formatAmount(item.amount, currencyCode)` to display them.
 - **startPayment()** — Opens the native sheet. Returns `Promise<PaymentResult | null>`.
   - Returns `null` and sets `error` when the cart is empty.
+  - Returns `null` and sets `error`, without opening the sheet, when an amount is invalid or the total is negative (see [`PaymentAmount`](/docs/api/types#paymentamount)).
   - Returns `PaymentResult` (including `{ success: false, error }`) when the native flow completes with a failure result.
   - Returns `null` if an exception is thrown while starting/processing the payment.
   - With `onAuthorize`, resolves after your callback settles. A `'failure'` result becomes `{ success: false, error }` and sets `error`.
@@ -104,10 +105,10 @@ const {
 // Single item
 addItem('Product', 29.99)
 
-// Multiple items
+// Multiple items; amounts can be numbers or decimal strings
 addItems([
   { label: 'Product', amount: 29.99 },
-  { label: 'Shipping', amount: 5 },
+  { label: 'Shipping', amount: '5.00' },
   { label: 'Tax', amount: 2.8, type: 'final' },
 ])
 
diff --git a/docs/docs/api/utils.md b/docs/docs/api/utils.md
index c4ee03e..c1323a9 100644
--- a/docs/docs/api/utils.md
+++ b/docs/docs/api/utils.md
@@ -16,24 +16,55 @@ Builds a full `PaymentRequest` with one line item and sensible defaults.
 
 **Defaults:** `countryCode: 'US'`, `currencyCode: 'USD'`, `supportedNetworks: [CommonNetworks]`, `merchantCapabilities: ['3DS']`.
 
+The amount is validated with [`normalizePaymentRequest`](#normalizepaymentrequestrequest), so `createPaymentRequest` throws for an invalid amount, and the returned request holds it as a decimal string.
+
 ```ts
 import { createPaymentRequest } from '@gmisoftware/react-native-pay'
 
 const request = createPaymentRequest({
-  amount: 29.99,
+  amount: 29.99, // or '29.99'
   label: 'Coffee Subscription',
   countryCode: 'US',
   currencyCode: 'USD',
   // Optional: applePayMerchantIdentifier, googlePayMerchantId,
   // googlePayEnvironment, googlePayGateway, googlePayGatewayMerchantId, etc.
 })
-// request.paymentItems is a single item: [{ label: 'Coffee Subscription', amount: 29.99, type: 'final' }]
+// request.paymentItems is a single item: [{ label: 'Coffee Subscription', amount: '29.99', type: 'final' }]
 ```
 
 Use with `HybridPaymentHandler.startPayment(request)` for a manual flow.
 
 ---
 
+## normalizePaymentRequest(request)
+
+Validates every amount in `paymentItems` and `shippingMethods` and returns a copy in which each amount is a decimal string with the currency's number of decimal places. See [`PaymentAmount`](./types.md#paymentamount) for the rules.
+
+Call it before passing a request you built yourself to `HybridPaymentHandler.startPayment`. `createPaymentRequest` and `usePaymentCheckout` already call it.
+
+```ts
+import { HybridPaymentHandler, normalizePaymentRequest } from '@gmisoftware/react-native-pay'
+
+const request = normalizePaymentRequest({
+  countryCode: 'US',
+  currencyCode: 'USD',
+  paymentItems: [
+    { label: 'Book', amount: 19.9, type: 'final' },
+    { label: 'Discount', amount: '-5', type: 'final' },
+  ],
+  supportedNetworks: ['visa', 'mastercard'],
+  merchantCapabilities: ['3DS'],
+})
+// request.paymentItems amounts: '19.90', '-5.00'
+
+await HybridPaymentHandler.startPayment(request)
+
+normalizePaymentRequest({ ...request, paymentItems: [{ label: 'Fee', amount: 1.005, type: 'final' }] })
+// throws: Amount for "Fee" has more than 2 decimal places, which USD allows, got 1.005
+```
+
+---
+
 ## createPaymentItem(label, amount, type?)
 
 Creates a single `PaymentItem`.
@@ -42,37 +73,43 @@ Creates a single `PaymentItem`.
 import { createPaymentItem } from '@gmisoftware/react-native-pay'
 
 createPaymentItem('Subscription', 29.99, 'final')
-createPaymentItem('Shipping', 5, 'pending')
+createPaymentItem('Shipping', '5.00', 'pending')
 // type defaults to 'final'
 ```
 
+The amount is stored as given and validated when the payment starts.
+
 ---
 
 ## calculateTotal(items)
 
-Sums the `amount` of all items.
+Sums the `amount` of all items with exact decimal arithmetic, the same as native code, and returns the sum as a number. Returns `NaN` if an amount is invalid.
 
 ```ts
 import { calculateTotal, createPaymentItem } from '@gmisoftware/react-native-pay'
 
 const items = [
   createPaymentItem('Product', 29.99),
-  createPaymentItem('Tax', 2.4),
+  createPaymentItem('Tax', '2.40'),
 ]
 calculateTotal(items) // 32.39
+
+calculateTotal([createPaymentItem('A', 0.1), createPaymentItem('B', 0.2)]) // 0.3, not 0.30000000000000004
 ```
 
 ---
 
-## formatAmount(amount)
+## formatAmount(amount, currencyCode?)
 
-Formats a number to two decimal places.
+Formats a number or decimal string with the currency's number of decimal places (two when `currencyCode` is omitted), rounding half away from zero. Returns `'NaN'` for an invalid amount.
 
 ```ts
 import { formatAmount } from '@gmisoftware/react-native-pay'
 
-formatAmount(29.9)  // "29.90"
-formatAmount(100)   // "100.00"
+formatAmount(29.9)          // "29.90"
+formatAmount('100')         // "100.00"
+formatAmount(1.005)         // "1.01"
+formatAmount(1500, 'JPY')   // "1500"
 ```
 
 ---
diff --git a/docs/docs/guides/dynamic-cart.md b/docs/docs/guides/dynamic-cart.md
index 81a7476..cba7025 100644
--- a/docs/docs/guides/dynamic-cart.md
+++ b/docs/docs/guides/dynamic-cart.md
@@ -39,17 +39,19 @@ clearItems()       // empty the cart
 ## Example: quantity and discount
 
 ```ts
+import { formatAmount } from '@gmisoftware/react-native-pay'
+
 const { items, addItem, updateItem, removeItem, total } = usePaymentCheckout({ ... })
 
 // Add product with quantity
 const handleAddProduct = (name: string, unitPrice: number, quantity: number) => {
-  addItem(`${name} (×${quantity})`, unitPrice * quantity)
+  // 1.1 * 3 is 3.3000000000000003; round it to the currency's decimals
+  addItem(`${name} (×${quantity})`, formatAmount(unitPrice * quantity))
 }
 
-// Apply percentage discount
+// Apply percentage discount (a negative line item)
 const handleApplyDiscount = (percent: number) => {
-  const discount = -total * (percent / 100)
-  addItem('Discount', discount, 'final')
+  addItem('Discount', formatAmount(-total * (percent / 100)), 'final')
 }
 
 // Clear cart
@@ -61,6 +63,8 @@ const handleClearCart = () => {
 ## Rules
 
 - **At least one item** is required before `startPayment()`. Otherwise the hook sets an error and returns `null`.
-- **total** is derived from `items`; you don’t set it manually.
+- **total** is derived from `items`; you don’t set it manually. It is an exact decimal sum.
+- **Round computed amounts** with `formatAmount(value, currencyCode)`. `startPayment()` rejects amounts with more decimal places than the currency allows, which includes unrounded float results such as `1.1 * 3`. See [`PaymentAmount`](/docs/api/types#paymentamount).
+- **Discounts** can be negative line items, as long as the total is not negative.
 - Use **type: 'final'** for confirmed amounts (e.g. tax, total); use **'pending'** for estimates (e.g. shipping) if your flow supports it.
 - **One pending item makes the total an estimate.** Google Pay shows the total as estimated (`totalPriceStatus: 'ESTIMATED'`) and Apple Pay marks the total as pending. An estimate does not let you charge a different amount: Google Pay requires the amount you authorize and charge to match the `totalPrice` shown on the sheet, and a mismatch can be declined. If the final amount differs from the estimate, start a new payment with the final amount, unless your gateway explicitly supports adjusting it (for example, incremental authorization).
diff --git a/docs/docs/guides/manual-flow.md b/docs/docs/guides/manual-flow.md
index f057d56..55593a7 100644
--- a/docs/docs/guides/manual-flow.md
+++ b/docs/docs/guides/manual-flow.md
@@ -33,7 +33,7 @@ const paymentRequest = createPaymentRequest({
 })
 ```
 
-For multiple line items, build `paymentItems` yourself and pass the full `PaymentRequest`. On iOS, the Merchant ID is read from the app entitlements unless you explicitly pass `applePayMerchantIdentifier`.
+`createPaymentRequest` throws if the amount is invalid (see [`PaymentAmount`](/docs/api/types#paymentamount)). For multiple line items, build `paymentItems` yourself and pass the full `PaymentRequest` through `normalizePaymentRequest`, which applies the same checks. On iOS, the Merchant ID is read from the app entitlements unless you explicitly pass `applePayMerchantIdentifier`.
 
 ## 3. Handle the button press
 
diff --git a/docs/docs/quick-start.md b/docs/docs/quick-start.md
index 02c3c30..25b460a 100644
--- a/docs/docs/quick-start.md
+++ b/docs/docs/quick-start.md
@@ -50,6 +50,7 @@ import {
   usePaymentCheckout,
   ApplePayButton,
   GooglePayButton,
+  formatAmount,
 } from '@gmisoftware/react-native-pay'
 import { Platform, View, Text, Button, ActivityIndicator } from 'react-native'
 
@@ -98,7 +99,7 @@ function CheckoutScreen() {
       <Button title="Add Coffee ($4.99)" onPress={() => addItem('Coffee', 4.99)} />
       {items.map((item, i) => (
         <View key={i} style={{ flexDirection: 'row', padding: 10 }}>
-          <Text>{item.label}: ${item.amount.toFixed(2)}</Text>
+          <Text>{item.label}: ${formatAmount(item.amount)}</Text>
           <Button title="Remove" onPress={() => removeItem(i)} />
         </View>
       ))}
diff --git a/example/app/(tabs)/index.tsx b/example/app/(tabs)/index.tsx
index 3c1aaab..b88dc05 100644
--- a/example/app/(tabs)/index.tsx
+++ b/example/app/(tabs)/index.tsx
@@ -11,6 +11,7 @@ import {
 import { Text, View } from "@/components/Themed";
 import {
   ApplePayButton,
+  formatAmount,
   GooglePayButton,
   usePaymentCheckout,
 } from "@gmisoftware/react-native-pay";
@@ -235,7 +236,7 @@ export default function TabOneScreen() {
             {items.map((item, index) => (
               <View key={index} style={styles.cartItem}>
                 <Text style={styles.itemLabel}>{item.label}</Text>
-                <Text style={styles.itemAmount}>${item.amount.toFixed(2)}</Text>
+                <Text style={styles.itemAmount}>${formatAmount(item.amount)}</Text>
               </View>
             ))}
 
diff --git a/package/android/src/main/java/com/margelo/nitro/pay/GooglePayRequestBuilder.kt b/package/android/src/main/java/com/margelo/nitro/pay/GooglePayRequestBuilder.kt
index 90a4da0..14265a8 100644
--- a/package/android/src/main/java/com/margelo/nitro/pay/GooglePayRequestBuilder.kt
+++ b/package/android/src/main/java/com/margelo/nitro/pay/GooglePayRequestBuilder.kt
@@ -3,13 +3,13 @@ package com.margelo.nitro.pay
 import com.google.android.gms.wallet.WalletConstants
 import org.json.JSONArray
 import org.json.JSONObject
-import java.util.Locale
+import java.math.BigDecimal
+import java.math.RoundingMode
 
 /**
  * Builder for Google Pay API request objects
  */
 object GooglePayRequestBuilder {
-    private val googlePayPriceLocale = Locale.US
     
     /**
      * Creates an IsReadyToPay request
@@ -144,7 +144,10 @@ object GooglePayRequestBuilder {
      * Creates transaction info
      */
     private fun createTransactionInfo(request: PaymentRequest): JSONObject {
-        val totalAmount = request.paymentItems.sumOf { it.amount }
+        val totalAmount = PaymentAmounts.total(request.paymentItems)
+        require(totalAmount.signum() >= 0) {
+            "Payment total must not be negative, got ${totalAmount.toPlainString()}"
+        }
         val hasPendingItems = request.paymentItems.any { it.type == PaymentItemType.PENDING }
         
         return JSONObject().apply {
@@ -176,7 +179,7 @@ object GooglePayRequestBuilder {
                 put(JSONObject().apply {
                     put("label", item.label)
                     put("type", PaymentConstants.LINE_ITEM_TYPE)
-                    put("price", formatPrice(item.amount))
+                    put("price", formatPrice(PaymentAmounts.parse(item)))
                     put(
                         "status",
                         if (item.type == PaymentItemType.PENDING)
@@ -189,8 +192,20 @@ object GooglePayRequestBuilder {
         }
     }
 
-    private fun formatPrice(amount: Double): String {
-        return String.format(googlePayPriceLocale, "%.2f", amount)
+    /**
+     * Google Pay accepts whole amounts or exactly two decimal places
+     * (`^[0-9]+(\.[0-9][0-9])?$` for the total).
+     */
+    private fun formatPrice(amount: BigDecimal): String {
+        val scale = if (amount.scale() <= 0) 0 else 2
+        return try {
+            amount.setScale(scale, RoundingMode.UNNECESSARY).toPlainString()
+        } catch (e: ArithmeticException) {
+            throw IllegalArgumentException(
+                "Google Pay accepts at most two decimal places, got ${amount.toPlainString()}",
+                e
+            )
+        }
     }
     
     /**
diff --git a/package/android/src/main/java/com/margelo/nitro/pay/PaymentAmounts.kt b/package/android/src/main/java/com/margelo/nitro/pay/PaymentAmounts.kt
new file mode 100644
index 0000000..3373101
--- /dev/null
+++ b/package/android/src/main/java/com/margelo/nitro/pay/PaymentAmounts.kt
@@ -0,0 +1,32 @@
+package com.margelo.nitro.pay
+
+import java.math.BigDecimal
+
+/**
+ * Exact decimal handling for payment amounts.
+ *
+ * Amounts are parsed and summed as [BigDecimal], never as Double.
+ */
+object PaymentAmounts {
+    private val decimalPattern = Regex("^-?[0-9]+(\\.[0-9]+)?$")
+
+    /**
+     * Parses an item amount. Numbers are read through their shortest
+     * round-trip form, so 19.99 becomes exactly 19.99.
+     */
+    fun parse(item: PaymentItem): BigDecimal {
+        val amount = when (val value = item.amount) {
+            is PaymentAmount.First ->
+                value.value.takeIf { it.isFinite() }?.let { BigDecimal.valueOf(it) }
+            is PaymentAmount.Second ->
+                value.value.takeIf { decimalPattern.matches(it) }?.let { BigDecimal(it) }
+        }
+        return requireNotNull(amount) {
+            "Amount for \"${item.label}\" must be a finite number or a decimal string like \"19.99\""
+        }
+    }
+
+    fun total(items: Array<PaymentItem>): BigDecimal {
+        return items.fold(BigDecimal.ZERO) { sum, item -> sum.add(parse(item)) }
+    }
+}
diff --git a/package/android/src/test/java/com/margelo/nitro/pay/GooglePayRequestBuilderTest.kt b/package/android/src/test/java/com/margelo/nitro/pay/GooglePayRequestBuilderTest.kt
index e4b3f0a..5102ddf 100644
--- a/package/android/src/test/java/com/margelo/nitro/pay/GooglePayRequestBuilderTest.kt
+++ b/package/android/src/test/java/com/margelo/nitro/pay/GooglePayRequestBuilderTest.kt
@@ -11,10 +11,14 @@ import org.junit.Test
 class GooglePayRequestBuilderTest {
 
     private fun item(label: String, amount: Double, type: PaymentItemType) =
-        PaymentItem(label = label, amount = amount, type = type)
+        PaymentItem(label = label, amount = PaymentAmount.create(amount), type = type)
+
+    private fun item(label: String, amount: String, type: PaymentItemType = PaymentItemType.FINAL) =
+        PaymentItem(label = label, amount = PaymentAmount.create(amount), type = type)
 
     private fun paymentRequest(
         items: Array<PaymentItem>,
+        currencyCode: String = "USD",
         merchantName: String? = null,
         environment: GooglePayEnvironment? = null,
         googlePayMerchantId: String? = null,
@@ -24,7 +28,7 @@ class GooglePayRequestBuilderTest {
         applePayMerchantIdentifier = null,
         merchantName = merchantName,
         countryCode = "US",
-        currencyCode = "USD",
+        currencyCode = currencyCode,
         paymentItems = items,
         merchantCapabilities = arrayOf("3DS"),
         supportedNetworks = arrayOf("visa"),
@@ -56,6 +60,9 @@ class GooglePayRequestBuilderTest {
     private fun JSONObject.totalPriceStatus(): String =
         getJSONObject("transactionInfo").getString("totalPriceStatus")
 
+    private fun JSONObject.totalPrice(): String =
+        getJSONObject("transactionInfo").getString("totalPrice")
+
     // Display items and total status
 
     @Test
@@ -121,6 +128,67 @@ class GooglePayRequestBuilderTest {
         assertFalse(json.toString().contains("\"type\":\"PENDING\""))
     }
 
+    // Amounts
+
+    @Test
+    fun totalPrice_isTheExactSumOfTheItems() {
+        val json = build(
+            paymentRequest(
+                arrayOf(
+                    item("Book", "19.99"),
+                    item("Book", 19.99, PaymentItemType.FINAL),
+                    item("Fee", "0.01")
+                )
+            )
+        )
+
+        assertEquals("39.99", json.totalPrice())
+        assertEquals(listOf("19.99", "19.99", "0.01"), json.displayItems().map { it.getString("price") })
+    }
+
+    @Test
+    fun prices_haveTwoDecimalsOrNone() {
+        assertEquals("10.00", build(paymentRequest(arrayOf(item("Item", "10.0")))).totalPrice())
+        assertEquals(
+            "1500",
+            build(paymentRequest(arrayOf(item("Item", "1500")), currencyCode = "JPY")).totalPrice()
+        )
+        assertEquals(
+            "10000000",
+            build(paymentRequest(arrayOf(item("Item", 1.0E7, PaymentItemType.FINAL)))).totalPrice()
+        )
+    }
+
+    @Test
+    fun negativeLineItems_areSentWhenTheTotalIsNotNegative() {
+        val json = build(paymentRequest(arrayOf(item("Item", "20.00"), item("Discount", "-5.00"))))
+
+        assertEquals("15.00", json.totalPrice())
+        assertEquals(listOf("20.00", "-5.00"), json.displayItems().map { it.getString("price") })
+    }
+
+    @Test
+    fun negativeTotal_isRejected() {
+        val error = assertThrows(IllegalArgumentException::class.java) {
+            build(paymentRequest(arrayOf(item("Item", "5.00"), item("Discount", "-5.01"))))
+        }
+
+        assertTrue(error.message!!.contains("must not be negative, got -0.01"))
+    }
+
+    @Test
+    fun thirdDecimalPlace_isRejectedInsteadOfRounded() {
+        assertEquals(
+            "1.23",
+            build(paymentRequest(arrayOf(item("Item", "1.230")), currencyCode = "KWD")).totalPrice()
+        )
+
+        val error = assertThrows(IllegalArgumentException::class.java) {
+            build(paymentRequest(arrayOf(item("Item", "1.234")), currencyCode = "KWD"))
+        }
+        assertTrue(error.message!!.contains("at most two decimal places, got 1.234"))
+    }
+
     // Merchant name
 
     private fun JSONObject.merchantInfo(): JSONObject = getJSONObject("merchantInfo")
diff --git a/package/android/src/test/java/com/margelo/nitro/pay/PaymentAmountsTest.kt b/package/android/src/test/java/com/margelo/nitro/pay/PaymentAmountsTest.kt
new file mode 100644
index 0000000..6d70ce7
--- /dev/null
+++ b/package/android/src/test/java/com/margelo/nitro/pay/PaymentAmountsTest.kt
@@ -0,0 +1,57 @@
+package com.margelo.nitro.pay
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertThrows
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import java.math.BigDecimal
+
+class PaymentAmountsTest {
+
+    private fun item(amount: Double) =
+        PaymentItem("Item", PaymentAmount.create(amount), PaymentItemType.FINAL)
+
+    private fun item(amount: String) =
+        PaymentItem("Item", PaymentAmount.create(amount), PaymentItemType.FINAL)
+
+    @Test
+    fun parse_readsStringsExactly() {
+        assertEquals(BigDecimal("19.99"), PaymentAmounts.parse(item("19.99")))
+        assertEquals(BigDecimal("-5.00"), PaymentAmounts.parse(item("-5.00")))
+    }
+
+    @Test
+    fun parse_readsNumbersThroughTheirShortestDecimalForm() {
+        assertEquals(BigDecimal("19.99"), PaymentAmounts.parse(item(19.99)))
+        assertEquals(BigDecimal("1234.56"), PaymentAmounts.parse(item(1234.56)))
+        assertEquals(0, BigDecimal("10000000").compareTo(PaymentAmounts.parse(item(1.0E7))))
+    }
+
+    @Test
+    fun parse_rejectsNonDecimalAmounts() {
+        val invalid = listOf(
+            item(Double.NaN),
+            item(Double.POSITIVE_INFINITY),
+            item("12abc"),
+            item(" 1.00"),
+            item("1,00"),
+            item("1e3"),
+            item("")
+        )
+
+        invalid.forEach { candidate ->
+            val error = assertThrows(IllegalArgumentException::class.java) {
+                PaymentAmounts.parse(candidate)
+            }
+            assertTrue(error.message!!.contains("finite number or a decimal string"))
+        }
+    }
+
+    @Test
+    fun total_isTheExactDecimalSum() {
+        val tenDimes = Array(10) { item(0.1) }
+
+        assertEquals(BigDecimal("5.49"), PaymentAmounts.total(arrayOf(item(4.99), item("0.50"))))
+        assertEquals(0, BigDecimal.ONE.compareTo(PaymentAmounts.total(tenDimes)))
+    }
+}
diff --git a/package/ios/HybridPaymentHandler.swift b/package/ios/HybridPaymentHandler.swift
index f4864ba..02a13dc 100644
--- a/package/ios/HybridPaymentHandler.swift
+++ b/package/ios/HybridPaymentHandler.swift
@@ -13,6 +13,17 @@ private enum ErrorMessage {
     static let unableToCreate = "Unable to create payment authorization"
     static let authorizationFailed = "Payment authorization failed"
     static let authorizationTimedOut = "Payment authorization timed out"
+    static let negativeTotal = "Payment total must not be negative"
+
+    static func invalidAmount(_ label: String) -> String {
+        return "Amount for \"\(label)\" must be a finite number or a decimal string like \"19.99\""
+    }
+}
+
+private struct PaymentRequestError: LocalizedError {
+    let message: String
+
+    var errorDescription: String? { message }
 }
 
 // PassKit fails the sheet on its own when the authorization completion is not
@@ -29,9 +40,9 @@ private enum BundleKey {
 
 private struct PaymentRequestBuilder {
     
-    static func build(from request: PaymentRequest) -> PKPaymentRequest? {
+    static func build(from request: PaymentRequest) throws -> PKPaymentRequest {
         guard let merchantIdentifier = resolveMerchantIdentifier(from: request) else {
-            return nil
+            throw PaymentRequestError(message: ErrorMessage.missingMerchantIdentifier)
         }
 
         let paymentRequest = PKPaymentRequest()
@@ -39,7 +50,7 @@ private struct PaymentRequestBuilder {
         paymentRequest.merchantIdentifier = merchantIdentifier
         paymentRequest.countryCode = request.countryCode
         paymentRequest.currencyCode = request.currencyCode
-        paymentRequest.paymentSummaryItems = buildPaymentItems(for: request)
+        paymentRequest.paymentSummaryItems = try buildPaymentItems(for: request)
         paymentRequest.merchantCapabilities = buildMerchantCapabilities(request.merchantCapabilities)
         paymentRequest.supportedNetworks = buildSupportedNetworks(request.supportedNetworks)
         
@@ -76,12 +87,22 @@ private struct PaymentRequestBuilder {
         return nil
     }
     
-    private static func buildPaymentItems(for request: PaymentRequest) -> [PKPaymentSummaryItem] {
-        let lineItems = request.paymentItems.map { item in
-            let pkItem = PKPaymentSummaryItem(
-                label: item.label,
-                amount: NSDecimalNumber(decimal: Decimal(item.amount))
-            )
+    private static func buildPaymentItems(for request: PaymentRequest) throws -> [PKPaymentSummaryItem] {
+        let amounts = try request.paymentItems.map { item -> NSDecimalNumber in
+            guard let amount = item.amount.decimalNumber else {
+                throw PaymentRequestError(message: ErrorMessage.invalidAmount(item.label))
+            }
+            return amount
+        }
+        let totalAmount = amounts.reduce(Decimal.zero) { partialResult, amount in
+            partialResult + amount.decimalValue
+        }
+        guard totalAmount >= Decimal.zero else {
+            throw PaymentRequestError(message: ErrorMessage.negativeTotal)
+        }
+
+        let lineItems = zip(request.paymentItems, amounts).map { item, amount in
+            let pkItem = PKPaymentSummaryItem(label: item.label, amount: amount)
             pkItem.type = item.type == .final ? .final : .pending
             return pkItem
         }
@@ -90,9 +111,6 @@ private struct PaymentRequestBuilder {
             return lineItems
         }
 
-        let totalAmount = request.paymentItems.reduce(Decimal.zero) { partialResult, item in
-            partialResult + Decimal(item.amount)
-        }
         let totalLabel: String
         if let merchantName = request.merchantName?
             .trimmingCharacters(in: CharacterSet.whitespacesAndNewlines),
@@ -384,8 +402,11 @@ class HybridPaymentHandler: HybridPaymentHandlerSpec {
             return
         }
 
-        guard let paymentRequest = PaymentRequestBuilder.build(from: request) else {
-            completion(PaymentResultFactory.failure(ErrorMessage.missingMerchantIdentifier))
+        let paymentRequest: PKPaymentRequest
+        do {
+            paymentRequest = try PaymentRequestBuilder.build(from: request)
+        } catch {
+            completion(PaymentResultFactory.failure(error.localizedDescription))
             return
         }
         
diff --git a/package/ios/PaymentAmount+Decimal.swift b/package/ios/PaymentAmount+Decimal.swift
new file mode 100644
index 0000000..87f5902
--- /dev/null
+++ b/package/ios/PaymentAmount+Decimal.swift
@@ -0,0 +1,28 @@
+import Foundation
+
+extension PaymentAmount {
+    private static let decimalPattern = "^-?[0-9]+(\\.[0-9]+)?$"
+    private static let posixLocale = Locale(identifier: "en_US_POSIX")
+
+    /// The exact decimal value, or `nil` unless the amount is a plain decimal.
+    ///
+    /// Numbers are read through their shortest round-trip description, so
+    /// `19.99` becomes exactly 19.99. `Decimal(19.99)` would give
+    /// 19.98999999999999488.
+    var decimalNumber: NSDecimalNumber? {
+        let text: String
+        switch self {
+        case .first(let number):
+            guard number.isFinite else { return nil }
+            text = "\(number)"
+        case .second(let string):
+            text = string
+        }
+
+        guard text.range(of: Self.decimalPattern, options: .regularExpression) != nil else {
+            return nil
+        }
+        let decimal = NSDecimalNumber(string: text, locale: Self.posixLocale)
+        return decimal == NSDecimalNumber.notANumber ? nil : decimal
+    }
+}
diff --git a/package/nitrogen/generated/android/NitroPay+autolinking.cmake b/package/nitrogen/generated/android/NitroPay+autolinking.cmake
index 3265e57..0dba5ee 100644
--- a/package/nitrogen/generated/android/NitroPay+autolinking.cmake
+++ b/package/nitrogen/generated/android/NitroPay+autolinking.cmake
@@ -42,6 +42,7 @@ target_sources(
   ../nitrogen/generated/android/c++/JHybridGooglePayButtonSpec.cpp
   ../nitrogen/generated/android/c++/views/JHybridGooglePayButtonStateUpdater.cpp
   ../nitrogen/generated/android/c++/JHybridPaymentHandlerSpec.cpp
+  ../nitrogen/generated/android/c++/JPaymentAmount.cpp
 )
 
 # From node_modules/react-native/ReactAndroid/cmake-utils/folly-flags.cmake
diff --git a/package/nitrogen/generated/android/c++/JHybridPaymentHandlerSpec.cpp b/package/nitrogen/generated/android/c++/JHybridPaymentHandlerSpec.cpp
index d4f31b5..3b85eda 100644
--- a/package/nitrogen/generated/android/c++/JHybridPaymentHandlerSpec.cpp
+++ b/package/nitrogen/generated/android/c++/JHybridPaymentHandlerSpec.cpp
@@ -91,6 +91,8 @@ namespace margelo::nitro::pay { enum class PaymentAuthorizationStatus; }
 #include "JPaymentRequest.hpp"
 #include "PaymentItem.hpp"
 #include "JPaymentItem.hpp"
+#include <variant>
+#include "JPaymentAmount.hpp"
 #include "PaymentItemType.hpp"
 #include "JPaymentItemType.hpp"
 #include "GooglePayEnvironment.hpp"
diff --git a/package/nitrogen/generated/android/c++/JPaymentAmount.cpp b/package/nitrogen/generated/android/c++/JPaymentAmount.cpp
new file mode 100644
index 0000000..b6d9ffe
--- /dev/null
+++ b/package/nitrogen/generated/android/c++/JPaymentAmount.cpp
@@ -0,0 +1,26 @@
+///
+/// JPaymentAmount.cpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#include "JPaymentAmount.hpp"
+
+namespace margelo::nitro::pay {
+  /**
+   * Converts JPaymentAmount to std::variant<double, std::string>
+   */
+  std::variant<double, std::string> JPaymentAmount::toCpp() const {
+    if (isInstanceOf(JPaymentAmount_impl::First::javaClassStatic())) {
+      // It's a `double`
+      auto jniValue = static_cast<const JPaymentAmount_impl::First*>(this)->getValue();
+      return jniValue;
+    } else if (isInstanceOf(JPaymentAmount_impl::Second::javaClassStatic())) {
+      // It's a `std::string`
+      auto jniValue = static_cast<const JPaymentAmount_impl::Second*>(this)->getValue();
+      return jniValue->toStdString();
+    }
+    throw std::invalid_argument("Variant is unknown Kotlin instance!");
+  }
+} // namespace margelo::nitro::pay
diff --git a/package/nitrogen/generated/android/c++/JPaymentAmount.hpp b/package/nitrogen/generated/android/c++/JPaymentAmount.hpp
new file mode 100644
index 0000000..7c8eb2a
--- /dev/null
+++ b/package/nitrogen/generated/android/c++/JPaymentAmount.hpp
@@ -0,0 +1,68 @@
+///
+/// JPaymentAmount.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#include <fbjni/fbjni.h>
+#include <variant>
+
+#include <string>
+#include <variant>
+
+namespace margelo::nitro::pay {
+
+  using namespace facebook;
+
+  /**
+   * The C++ JNI bridge between the C++ std::variant and the Java class "PaymentAmount".
+   */
+  class JPaymentAmount: public jni::JavaClass<JPaymentAmount> {
+  public:
+    static constexpr auto kJavaDescriptor = "Lcom/margelo/nitro/pay/PaymentAmount;";
+
+    static jni::local_ref<JPaymentAmount> create_0(double value) {
+      static const auto method = javaClassStatic()->getStaticMethod<JPaymentAmount(double)>("create");
+      return method(javaClassStatic(), value);
+    }
+    static jni::local_ref<JPaymentAmount> create_1(jni::alias_ref<jni::JString> value) {
+      static const auto method = javaClassStatic()->getStaticMethod<JPaymentAmount(jni::alias_ref<jni::JString>)>("create");
+      return method(javaClassStatic(), value);
+    }
+
+    static jni::local_ref<JPaymentAmount> fromCpp(const std::variant<double, std::string>& variant) {
+      switch (variant.index()) {
+        case 0: return create_0(std::get<0>(variant));
+        case 1: return create_1(jni::make_jstring(std::get<1>(variant)));
+        default: throw std::invalid_argument("Variant holds unknown index! (" + std::to_string(variant.index()) + ")");
+      }
+    }
+
+    [[nodiscard]] std::variant<double, std::string> toCpp() const;
+  };
+
+  namespace JPaymentAmount_impl {
+    class First final: public jni::JavaClass<First, JPaymentAmount> {
+    public:
+      static constexpr auto kJavaDescriptor = "Lcom/margelo/nitro/pay/PaymentAmount$First;";
+    
+      [[nodiscard]] double getValue() const {
+        static const auto field = javaClassStatic()->getField<double>("value");
+        return getFieldValue(field);
+      }
+    };
+    
+    class Second final: public jni::JavaClass<Second, JPaymentAmount> {
+    public:
+      static constexpr auto kJavaDescriptor = "Lcom/margelo/nitro/pay/PaymentAmount$Second;";
+    
+      [[nodiscard]] jni::local_ref<jni::JString> getValue() const {
+        static const auto field = javaClassStatic()->getField<jni::JString>("value");
+        return getFieldValue(field);
+      }
+    };
+  } // namespace JPaymentAmount_impl
+} // namespace margelo::nitro::pay
diff --git a/package/nitrogen/generated/android/c++/JPaymentItem.hpp b/package/nitrogen/generated/android/c++/JPaymentItem.hpp
index 4aac673..b30e42e 100644
--- a/package/nitrogen/generated/android/c++/JPaymentItem.hpp
+++ b/package/nitrogen/generated/android/c++/JPaymentItem.hpp
@@ -10,9 +10,11 @@
 #include <fbjni/fbjni.h>
 #include "PaymentItem.hpp"
 
+#include "JPaymentAmount.hpp"
 #include "JPaymentItemType.hpp"
 #include "PaymentItemType.hpp"
 #include <string>
+#include <variant>
 
 namespace margelo::nitro::pay {
 
@@ -35,13 +37,13 @@ namespace margelo::nitro::pay {
       static const auto clazz = javaClassStatic();
       static const auto fieldLabel = clazz->getField<jni::JString>("label");
       jni::local_ref<jni::JString> label = this->getFieldValue(fieldLabel);
-      static const auto fieldAmount = clazz->getField<double>("amount");
-      double amount = this->getFieldValue(fieldAmount);
+      static const auto fieldAmount = clazz->getField<JPaymentAmount>("amount");
+      jni::local_ref<JPaymentAmount> amount = this->getFieldValue(fieldAmount);
       static const auto fieldType = clazz->getField<JPaymentItemType>("type");
       jni::local_ref<JPaymentItemType> type = this->getFieldValue(fieldType);
       return PaymentItem(
         label->toStdString(),
-        amount,
+        amount->toCpp(),
         type->toCpp()
       );
     }
@@ -52,13 +54,13 @@ namespace margelo::nitro::pay {
      */
     [[maybe_unused]]
     static jni::local_ref<JPaymentItem::javaobject> fromCpp(const PaymentItem& value) {
-      using JSignature = JPaymentItem(jni::alias_ref<jni::JString>, double, jni::alias_ref<JPaymentItemType>);
+      using JSignature = JPaymentItem(jni::alias_ref<jni::JString>, jni::alias_ref<JPaymentAmount>, jni::alias_ref<JPaymentItemType>);
       static const auto clazz = javaClassStatic();
       static const auto create = clazz->getStaticMethod<JSignature>("fromCpp");
       return create(
         clazz,
         jni::make_jstring(value.label),
-        value.amount,
+        JPaymentAmount::fromCpp(value.amount),
         JPaymentItemType::fromCpp(value.type)
       );
     }
diff --git a/package/nitrogen/generated/android/c++/JPaymentRequest.hpp b/package/nitrogen/generated/android/c++/JPaymentRequest.hpp
index bc331de..10a2cac 100644
--- a/package/nitrogen/generated/android/c++/JPaymentRequest.hpp
+++ b/package/nitrogen/generated/android/c++/JPaymentRequest.hpp
@@ -12,12 +12,14 @@
 
 #include "GooglePayEnvironment.hpp"
 #include "JGooglePayEnvironment.hpp"
+#include "JPaymentAmount.hpp"
 #include "JPaymentItem.hpp"
 #include "JPaymentItemType.hpp"
 #include "PaymentItem.hpp"
 #include "PaymentItemType.hpp"
 #include <optional>
 #include <string>
+#include <variant>
 #include <vector>
 
 namespace margelo::nitro::pay {
diff --git a/package/nitrogen/generated/android/kotlin/com/margelo/nitro/pay/PaymentAmount.kt b/package/nitrogen/generated/android/kotlin/com/margelo/nitro/pay/PaymentAmount.kt
new file mode 100644
index 0000000..07b36a0
--- /dev/null
+++ b/package/nitrogen/generated/android/kotlin/com/margelo/nitro/pay/PaymentAmount.kt
@@ -0,0 +1,62 @@
+///
+/// PaymentAmount.kt
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+package com.margelo.nitro.pay
+
+import com.facebook.proguard.annotations.DoNotStrip
+
+
+/**
+ * Represents the TypeScript variant "Double | String".
+ */
+@Suppress("ClassName")
+@DoNotStrip
+sealed class PaymentAmount {
+  @DoNotStrip
+  data class First(@DoNotStrip val value: Double): PaymentAmount()
+  @DoNotStrip
+  data class Second(@DoNotStrip val value: String): PaymentAmount()
+
+  inline fun <reified T> asType(): T? {
+    return when (this) {
+      is First -> (value) as? T
+      is Second -> (value) as? T
+    }
+  }
+  inline fun <reified T> isType(): Boolean {
+    return asType<T>() != null
+  }
+  inline fun <R> match(first: (Double) -> R, second: (String) -> R): R {
+    return when (this) {
+      is First -> first(value)
+      is Second -> second(value)
+    }
+  }
+
+  val isFirst: Boolean
+    get() = this is First
+  val isSecond: Boolean
+    get() = this is Second
+
+  fun asFirstOrNull(): Double? {
+    val value = (this as? First)?.value ?: return null
+    return value
+  }
+  fun asSecondOrNull(): String? {
+    val value = (this as? Second)?.value ?: return null
+    return value
+  }
+
+  companion object {
+    @JvmStatic
+    @DoNotStrip
+    fun create(value: Double): PaymentAmount = First(value)
+    @JvmStatic
+    @DoNotStrip
+    fun create(value: String): PaymentAmount = Second(value)
+  }
+}
diff --git a/package/nitrogen/generated/android/kotlin/com/margelo/nitro/pay/PaymentItem.kt b/package/nitrogen/generated/android/kotlin/com/margelo/nitro/pay/PaymentItem.kt
index 40dc8ef..7cf6459 100644
--- a/package/nitrogen/generated/android/kotlin/com/margelo/nitro/pay/PaymentItem.kt
+++ b/package/nitrogen/generated/android/kotlin/com/margelo/nitro/pay/PaymentItem.kt
@@ -23,7 +23,7 @@ data class PaymentItem(
   val label: String,
   @DoNotStrip
   @Keep
-  val amount: Double,
+  val amount: PaymentAmount,
   @DoNotStrip
   @Keep
   val type: PaymentItemType
@@ -54,7 +54,7 @@ data class PaymentItem(
     @Keep
     @Suppress("unused")
     @JvmStatic
-    private fun fromCpp(label: String, amount: Double, type: PaymentItemType): PaymentItem {
+    private fun fromCpp(label: String, amount: PaymentAmount, type: PaymentItemType): PaymentItem {
       return PaymentItem(label, amount, type)
     }
   }
diff --git a/package/nitrogen/generated/ios/NitroPay-Swift-Cxx-Bridge.hpp b/package/nitrogen/generated/ios/NitroPay-Swift-Cxx-Bridge.hpp
index f1a8d48..234684b 100644
--- a/package/nitrogen/generated/ios/NitroPay-Swift-Cxx-Bridge.hpp
+++ b/package/nitrogen/generated/ios/NitroPay-Swift-Cxx-Bridge.hpp
@@ -93,6 +93,7 @@ namespace NitroPay { class HybridPaymentHandlerSpec_cxx; }
 #include <memory>
 #include <optional>
 #include <string>
+#include <variant>
 #include <vector>
 
 /**
@@ -329,6 +330,35 @@ namespace margelo::nitro::pay::bridge::swift {
     return Func_void_std__exception_ptr_Wrapper(std::move(value));
   }
   
+  // pragma MARK: std::variant<double, std::string>
+  /**
+   * Wrapper struct for `std::variant<double, std::string>`.
+   * std::variant cannot be used in Swift because of a Swift bug.
+   * Not even specializing it works. So we create a wrapper struct.
+   */
+  struct std__variant_double__std__string_ final {
+    std::variant<double, std::string> variant;
+    std__variant_double__std__string_(std::variant<double, std::string> variant): variant(variant) { }
+    operator std::variant<double, std::string>() const noexcept {
+      return variant;
+    }
+    inline size_t index() const noexcept {
+      return variant.index();
+    }
+    inline double get_0() const noexcept {
+      return std::get<0>(variant);
+    }
+    inline std::string get_1() const noexcept {
+      return std::get<1>(variant);
+    }
+  };
+  inline std__variant_double__std__string_ create_std__variant_double__std__string_(double value) noexcept {
+    return std__variant_double__std__string_(value);
+  }
+  inline std__variant_double__std__string_ create_std__variant_double__std__string_(const std::string& value) noexcept {
+    return std__variant_double__std__string_(value);
+  }
+  
   // pragma MARK: std::vector<PaymentItem>
   /**
    * Specialized version of `std::vector<PaymentItem>`.
diff --git a/package/nitrogen/generated/ios/NitroPay-Swift-Cxx-Umbrella.hpp b/package/nitrogen/generated/ios/NitroPay-Swift-Cxx-Umbrella.hpp
index 2c5898d..c9a6e9d 100644
--- a/package/nitrogen/generated/ios/NitroPay-Swift-Cxx-Umbrella.hpp
+++ b/package/nitrogen/generated/ios/NitroPay-Swift-Cxx-Umbrella.hpp
@@ -95,6 +95,7 @@ namespace margelo::nitro::pay { struct StartPaymentOptions; }
 #include <memory>
 #include <optional>
 #include <string>
+#include <variant>
 #include <vector>
 
 // C++ helpers for Swift
diff --git a/package/nitrogen/generated/ios/c++/HybridPaymentHandlerSpecSwift.hpp b/package/nitrogen/generated/ios/c++/HybridPaymentHandlerSpecSwift.hpp
index d4122fa..4ba54df 100644
--- a/package/nitrogen/generated/ios/c++/HybridPaymentHandlerSpecSwift.hpp
+++ b/package/nitrogen/generated/ios/c++/HybridPaymentHandlerSpecSwift.hpp
@@ -78,6 +78,7 @@ namespace margelo::nitro::pay { enum class PaymentAuthorizationStatus; }
 #include "CNPostalAddress.hpp"
 #include "PaymentRequest.hpp"
 #include "PaymentItem.hpp"
+#include <variant>
 #include "PaymentItemType.hpp"
 #include "GooglePayEnvironment.hpp"
 #include "StartPaymentOptions.hpp"
diff --git a/package/nitrogen/generated/ios/swift/PaymentAmount.swift b/package/nitrogen/generated/ios/swift/PaymentAmount.swift
new file mode 100644
index 0000000..bbc3984
--- /dev/null
+++ b/package/nitrogen/generated/ios/swift/PaymentAmount.swift
@@ -0,0 +1,30 @@
+///
+/// PaymentAmount.swift
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+
+
+/**
+ * An Swift enum with associated values representing a Variant/Union type.
+ * JS type: `number | string`
+ */
+@frozen
+public enum PaymentAmount {
+  case first(Double)
+  case second(String)
+}
+
+public extension PaymentAmount {
+  func asType<T>(_ type: T.Type = T.self) -> T? {
+    switch self {
+      case .first(let value): return value as? T
+      case .second(let value): return value as? T
+    }
+  }
+  func isType<T>(_ type: T.Type = T.self) -> Bool {
+    return self.asType(type) != nil
+  }
+}
diff --git a/package/nitrogen/generated/ios/swift/PaymentItem.swift b/package/nitrogen/generated/ios/swift/PaymentItem.swift
index db39c30..27783e1 100644
--- a/package/nitrogen/generated/ios/swift/PaymentItem.swift
+++ b/package/nitrogen/generated/ios/swift/PaymentItem.swift
@@ -18,8 +18,15 @@ public extension PaymentItem {
   /**
    * Create a new instance of `PaymentItem`.
    */
-  init(label: String, amount: Double, type: PaymentItemType) {
-    self.init(std.string(label), amount, type)
+  init(label: String, amount: PaymentAmount, type: PaymentItemType) {
+    self.init(std.string(label), { () -> bridge.std__variant_double__std__string_ in
+      switch amount {
+        case .first(let __value):
+          return bridge.create_std__variant_double__std__string_(__value)
+        case .second(let __value):
+          return bridge.create_std__variant_double__std__string_(std.string(__value))
+      }
+    }().variant, type)
   }
 
   @inline(__always)
@@ -28,8 +35,20 @@ public extension PaymentItem {
   }
   
   @inline(__always)
-  var amount: Double {
-    return self.__amount
+  var amount: PaymentAmount {
+    return { () -> PaymentAmount in
+      let __variant = bridge.std__variant_double__std__string_(self.__amount)
+      switch __variant.index() {
+        case 0:
+          let __actual = __variant.get_0()
+          return .first(__actual)
+        case 1:
+          let __actual = __variant.get_1()
+          return .second(String(__actual))
+        default:
+          fatalError("Variant can never have index \(__variant.index())!")
+      }
+    }()
   }
   
   @inline(__always)
diff --git a/package/nitrogen/generated/shared/c++/PaymentItem.hpp b/package/nitrogen/generated/shared/c++/PaymentItem.hpp
index dde7278..777e4b3 100644
--- a/package/nitrogen/generated/shared/c++/PaymentItem.hpp
+++ b/package/nitrogen/generated/shared/c++/PaymentItem.hpp
@@ -32,6 +32,7 @@
 namespace margelo::nitro::pay { enum class PaymentItemType; }
 
 #include <string>
+#include <variant>
 #include "PaymentItemType.hpp"
 
 namespace margelo::nitro::pay {
@@ -42,12 +43,12 @@ namespace margelo::nitro::pay {
   struct PaymentItem final {
   public:
     std::string label     SWIFT_PRIVATE;
-    double amount     SWIFT_PRIVATE;
+    std::variant<double, std::string> amount     SWIFT_PRIVATE;
     PaymentItemType type     SWIFT_PRIVATE;
 
   public:
     PaymentItem() = default;
-    explicit PaymentItem(std::string label, double amount, PaymentItemType type): label(label), amount(amount), type(type) {}
+    explicit PaymentItem(std::string label, std::variant<double, std::string> amount, PaymentItemType type): label(label), amount(amount), type(type) {}
 
   public:
     friend bool operator==(const PaymentItem& lhs, const PaymentItem& rhs) = default;
@@ -64,14 +65,14 @@ namespace margelo::nitro {
       jsi::Object obj = arg.asObject(runtime);
       return margelo::nitro::pay::PaymentItem(
         JSIConverter<std::string>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "label"))),
-        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "amount"))),
+        JSIConverter<std::variant<double, std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "amount"))),
         JSIConverter<margelo::nitro::pay::PaymentItemType>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "type")))
       );
     }
     static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::pay::PaymentItem& arg) {
       jsi::Object obj(runtime);
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "label"), JSIConverter<std::string>::toJSI(runtime, arg.label));
-      obj.setProperty(runtime, PropNameIDCache::get(runtime, "amount"), JSIConverter<double>::toJSI(runtime, arg.amount));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "amount"), JSIConverter<std::variant<double, std::string>>::toJSI(runtime, arg.amount));
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "type"), JSIConverter<margelo::nitro::pay::PaymentItemType>::toJSI(runtime, arg.type));
       return obj;
     }
@@ -84,7 +85,7 @@ namespace margelo::nitro {
         return false;
       }
       if (!JSIConverter<std::string>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "label")))) return false;
-      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "amount")))) return false;
+      if (!JSIConverter<std::variant<double, std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "amount")))) return false;
       if (!JSIConverter<margelo::nitro::pay::PaymentItemType>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "type")))) return false;
       return true;
     }
diff --git a/package/src/hooks/__tests__/usePaymentCheckout.integration.test.ts b/package/src/hooks/__tests__/usePaymentCheckout.integration.test.ts
index dc6a520..93e2db6 100644
--- a/package/src/hooks/__tests__/usePaymentCheckout.integration.test.ts
+++ b/package/src/hooks/__tests__/usePaymentCheckout.integration.test.ts
@@ -157,7 +157,7 @@ describe('usePaymentCheckout integration', () => {
     expect(mockStartPayment).toHaveBeenCalledTimes(1)
     expect(mockStartPayment).toHaveBeenCalledWith(
       expect.objectContaining({
-        paymentItems: [{ label: 'Coffee', amount: 4.99, type: 'final' }],
+        paymentItems: [{ label: 'Coffee', amount: '4.99', type: 'final' }],
       })
     )
     expect(paymentResult).toEqual(nativeSuccess)
@@ -166,6 +166,112 @@ describe('usePaymentCheckout integration', () => {
     expect(result.current.isProcessing).toBe(false)
   })
 
+  it('sends exact decimal strings for number and string amounts', async () => {
+    mockStartPayment.mockResolvedValueOnce({ success: true })
+    const { result } = renderHook(() =>
+      usePaymentCheckout({ currencyCode: 'USD' })
+    )
+
+    act(() => {
+      result.current.addItems([
+        { label: 'Book', amount: 19.99 },
+        { label: 'Gift wrap', amount: '19.99' },
+        { label: 'Discount', amount: '-5' },
+      ])
+    })
+
+    expect(result.current.total).toBe(34.98)
+
+    await act(async () => {
+      await result.current.startPayment()
+    })
+
+    expect(mockStartPayment).toHaveBeenCalledWith(
+      expect.objectContaining({
+        paymentItems: [
+          { label: 'Book', amount: '19.99', type: 'final' },
+          { label: 'Gift wrap', amount: '19.99', type: 'final' },
+          { label: 'Discount', amount: '-5.00', type: 'final' },
+        ],
+      })
+    )
+  })
+
+  it.each([
+    ['NaN', NaN, 'finite number or a decimal string'],
+    ['a negative total', -1, 'must not be negative'],
+    ['too many decimals for USD', 1.005, 'more than 2 decimal places'],
+    ['float arithmetic noise', 0.1 + 0.2, 'more than 2 decimal places'],
+  ])(
+    'rejects %s before calling native code',
+    async (_name, amount, message) => {
+      const { result } = renderCheckout()
+
+      act(() => {
+        result.current.addItem('Order', amount)
+      })
+
+      let paymentResult: any = 'not-called'
+      await act(async () => {
+        paymentResult = await result.current.startPayment()
+      })
+
+      expect(paymentResult).toBeNull()
+      expect(result.current.error?.message).toContain(message)
+      expect(result.current.isProcessing).toBe(false)
+      expect(mockStartPayment).not.toHaveBeenCalled()
+    }
+  )
+
+  it('rejects decimals in zero-decimal currencies', async () => {
+    const { result } = renderHook(() =>
+      usePaymentCheckout({ currencyCode: 'JPY' })
+    )
+
+    act(() => {
+      result.current.addItem('Ramen', '1200.5')
+    })
+
+    await act(async () => {
+      await result.current.startPayment()
+    })
+
+    expect(result.current.error?.message).toContain(
+      'more than 0 decimal places'
+    )
+    expect(mockStartPayment).not.toHaveBeenCalled()
+  })
+
+  it('starts the next payment after an amount is rejected', async () => {
+    mockStartPayment.mockResolvedValueOnce({ success: true })
+    const { result } = renderCheckout()
+
+    act(() => {
+      result.current.addItem('Order', 1.005)
+    })
+    await act(async () => {
+      await result.current.startPayment()
+    })
+    expect(mockStartPayment).not.toHaveBeenCalled()
+
+    act(() => {
+      result.current.updateItem(0, { amount: '1.01' })
+    })
+    let paymentResult: any = null
+    await act(async () => {
+      paymentResult = await result.current.startPayment()
+    })
+
+    expect(paymentResult).toEqual({ success: true })
+    expect(result.current.error).toBeNull()
+    expect(mockStartPayment).toHaveBeenCalledTimes(1)
+    expect(mockStartPayment).toHaveBeenCalledWith(
+      expect.objectContaining({
+        paymentItems: [{ label: 'Order', amount: '1.01', type: 'final' }],
+      })
+    )
+  })
+
   it('sets an error when native payment response has success=false', async () => {
     mockStartPayment.mockResolvedValueOnce({
       success: false,
@@ -277,6 +383,9 @@ describe('usePaymentCheckout integration', () => {
       expect(onAuthorize).toHaveBeenCalledWith(token)
       expect(paymentResult).toEqual({ success: true, token })
       expect(result.current.error).toBeNull()
+      expect(mockStartPayment.mock.calls[0]?.[0].paymentItems).toEqual([
+        { label: 'Order', amount: '12.00', type: 'final' },
+      ])
     })
 
     it('reports a failure from onAuthorize as an error', async () => {
diff --git a/package/src/hooks/usePaymentCheckout.ts b/package/src/hooks/usePaymentCheckout.ts
index 2c6edad..2bf3c59 100644
--- a/package/src/hooks/usePaymentCheckout.ts
+++ b/package/src/hooks/usePaymentCheckout.ts
@@ -1,6 +1,7 @@
 import { useState, useCallback, useMemo, useEffect, useRef } from 'react'
 import { getPaymentHandler, PAYMENT_IN_PROGRESS_ERROR } from '../paymentHandler'
 import type {
+  PaymentAmount,
   PaymentRequest,
   PaymentResult,
   PaymentItem,
@@ -12,6 +13,7 @@ import type {
 import {
   createPaymentItem,
   calculateTotal,
+  normalizePaymentRequest,
   sanitizePaymentRequest,
 } from '../utils'
 
@@ -100,10 +102,19 @@ export interface UsePaymentCheckoutReturn {
 
   // Cart management
   items: PaymentItem[]
+  /** Exact decimal sum of `items`; `NaN` if an amount is invalid. */
   total: number
-  addItem: (label: string, amount: number, type?: 'final' | 'pending') => void
+  addItem: (
+    label: string,
+    amount: PaymentAmount,
+    type?: 'final' | 'pending'
+  ) => void
   addItems: (
-    items: Array<{ label: string; amount: number; type?: 'final' | 'pending' }>
+    items: Array<{
+      label: string
+      amount: PaymentAmount
+      type?: 'final' | 'pending'
+    }>
   ) => void
   removeItem: (index: number) => void
   updateItem: (index: number, updates: Partial<PaymentItem>) => void
@@ -243,7 +254,11 @@ export function usePaymentCheckout(
 
   // Cart operations
   const addItem = useCallback(
-    (label: string, amount: number, type: 'final' | 'pending' = 'final') => {
+    (
+      label: string,
+      amount: PaymentAmount,
+      type: 'final' | 'pending' = 'final'
+    ) => {
       const item = createPaymentItem(label, amount, type)
       setItems((prev) => [...prev, item])
     },
@@ -254,7 +269,7 @@ export function usePaymentCheckout(
     (
       itemsToAdd: Array<{
         label: string
-        amount: number
+        amount: PaymentAmount
         type?: 'final' | 'pending'
       }>
     ) => {
@@ -294,6 +309,14 @@ export function usePaymentCheckout(
       return null
     }
 
+    let validatedRequest: PaymentRequest
+    try {
+      validatedRequest = normalizePaymentRequest(paymentRequest)
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)))
+      return null
+    }
+
     isPaymentInFlight.current = true
     setIsProcessing(true)
     setResult(null)
@@ -303,11 +326,11 @@ export function usePaymentCheckout(
 
     try {
       const paymentResult = onAuthorize
-        ? await getPaymentHandler().startPayment(paymentRequest, {
+        ? await getPaymentHandler().startPayment(validatedRequest, {
             // `async` turns a synchronous return or throw into the Promise native expects.
             onAuthorize: async (token) => onAuthorize(token),
           })
-        : await getPaymentHandler().startPayment(paymentRequest)
+        : await getPaymentHandler().startPayment(validatedRequest)
 
       setResult(paymentResult)
 
diff --git a/package/src/types/Payment.ts b/package/src/types/Payment.ts
index a628f62..cbd7e90 100644
--- a/package/src/types/Payment.ts
+++ b/package/src/types/Payment.ts
@@ -52,9 +52,18 @@ export interface PKSecureElementPass extends PKPass {
   pairedTerminalIdentifier?: string
 }
 
+/**
+ * A monetary amount in the currency's major unit: `'19.99'` or `19.99`.
+ *
+ * Decimal strings are exact. Numbers are read as the shortest decimal that
+ * round-trips (`19.99`, never `19.98999…`), so float arithmetic results such
+ * as `0.1 + 0.2` fail validation instead of being rounded silently.
+ */
+export type PaymentAmount = number | string
+
 export interface PaymentItem {
   label: string
-  amount: number
+  amount: PaymentAmount
   type: PaymentItemType
 }
 
diff --git a/package/src/utils/__tests__/amounts.test.ts b/package/src/utils/__tests__/amounts.test.ts
new file mode 100644
index 0000000..6970e0c
--- /dev/null
+++ b/package/src/utils/__tests__/amounts.test.ts
@@ -0,0 +1,147 @@
+import type { PaymentRequest } from '../../types'
+import {
+  getCurrencyMinorUnits,
+  normalizeAmount,
+  normalizePaymentRequest,
+} from '../amounts'
+
+const request = (
+  paymentItems: PaymentRequest['paymentItems'],
+  currencyCode = 'USD'
+): PaymentRequest => ({
+  countryCode: 'US',
+  currencyCode,
+  paymentItems,
+  supportedNetworks: ['visa'],
+  merchantCapabilities: ['3DS'],
+})
+
+describe('getCurrencyMinorUnits', () => {
+  it('follows ISO 4217 and defaults to 2', () => {
+    expect(getCurrencyMinorUnits('USD')).toBe(2)
+    expect(getCurrencyMinorUnits('jpy')).toBe(0)
+    expect(getCurrencyMinorUnits('KWD')).toBe(3)
+    expect(getCurrencyMinorUnits('CLF')).toBe(4)
+    expect(getCurrencyMinorUnits('XYZ')).toBe(2)
+  })
+})
+
+describe('normalizeAmount', () => {
+  it.each([
+    [19.99, 'USD', '19.99'],
+    ['19.99', 'USD', '19.99'],
+    [19.9, 'USD', '19.90'],
+    [10, 'USD', '10.00'],
+    ['1234.56', 'USD', '1234.56'],
+    ['1.500', 'USD', '1.50'],
+    ['-5', 'USD', '-5.00'],
+    ['-0.00', 'USD', '0.00'],
+    [0, 'USD', '0.00'],
+    [1500, 'JPY', '1500'],
+    ['1500.00', 'JPY', '1500'],
+    ['1.234', 'KWD', '1.234'],
+    [1.2, 'KWD', '1.200'],
+    ['90071992547409.99', 'USD', '90071992547409.99'],
+  ])('normalizes %p in %s to %p', (amount, currencyCode, expected) => {
+    expect(normalizeAmount(amount, currencyCode)).toBe(expected)
+  })
+
+  it.each([
+    [NaN],
+    [Infinity],
+    [-Infinity],
+    [1e21],
+    [1e-7],
+    [''],
+    [' 1.00'],
+    ['1,00'],
+    ['1.'],
+    ['.5'],
+    ['+1'],
+    ['1e3'],
+    ['NaN'],
+    [null as unknown as number],
+  ])('rejects malformed amount %p', (amount) => {
+    expect(() => normalizeAmount(amount, 'USD')).toThrow(
+      'must be a finite number or a decimal string'
+    )
+  })
+
+  it.each([
+    [1.005, 'USD'],
+    ['19.999', 'USD'],
+    [0.1 + 0.2, 'USD'],
+    ['1.5', 'JPY'],
+    ['1.2345', 'KWD'],
+  ])('rejects %p as too precise for %s', (amount, currencyCode) => {
+    expect(() => normalizeAmount(amount, currencyCode)).toThrow(
+      'decimal places'
+    )
+  })
+
+  it('names the item in error messages', () => {
+    expect(() => normalizeAmount(1.005, 'USD', 'Coffee')).toThrow(
+      'Amount for "Coffee" has more than 2 decimal places, which USD allows, got 1.005'
+    )
+  })
+})
+
+describe('normalizePaymentRequest', () => {
+  it('converts every item to an exact decimal string', () => {
+    const normalized = normalizePaymentRequest(
+      request([
+        { label: 'Coffee', amount: 4.99, type: 'final' },
+        { label: 'Tip', amount: '0.5', type: 'pending' },
+      ])
+    )
+
+    expect(normalized.paymentItems).toEqual([
+      { label: 'Coffee', amount: '4.99', type: 'final' },
+      { label: 'Tip', amount: '0.50', type: 'pending' },
+    ])
+  })
+
+  it('allows negative line items when the total is not negative', () => {
+    const normalized = normalizePaymentRequest(
+      request([
+        { label: 'Product', amount: 10, type: 'final' },
+        { label: 'Discount', amount: -10, type: 'final' },
+      ])
+    )
+
+    expect(normalized.paymentItems.map((item) => item.amount)).toEqual([
+      '10.00',
+      '-10.00',
+    ])
+  })
+
+  it('rejects a negative total', () => {
+    expect(() =>
+      normalizePaymentRequest(
+        request([
+          { label: 'Product', amount: '10', type: 'final' },
+          { label: 'Discount', amount: '-10.01', type: 'final' },
+        ])
+      )
+    ).toThrow('Payment total must not be negative, got -0.01')
+  })
+
+  it('normalizes shipping methods', () => {
+    const normalized = normalizePaymentRequest({
+      ...request([{ label: 'Product', amount: 10, type: 'final' }]),
+      shippingMethods: [{ label: 'Express', amount: 7.5, type: 'final' }],
+    })
+
+    expect(normalized.shippingMethods).toEqual([
+      { label: 'Express', amount: '7.50', type: 'final' },
+    ])
+  })
+
+  it('does not modify the input request', () => {
+    const input = request([{ label: 'Product', amount: 10, type: 'final' }])
+
+    normalizePaymentRequest(input)
+
+    expect(input.paymentItems[0]?.amount).toBe(10)
+  })
+})
diff --git a/package/src/utils/__tests__/paymentHelpers.test.ts b/package/src/utils/__tests__/paymentHelpers.test.ts
index a5cb5e4..60be0d1 100644
--- a/package/src/utils/__tests__/paymentHelpers.test.ts
+++ b/package/src/utils/__tests__/paymentHelpers.test.ts
@@ -34,6 +34,31 @@ describe('paymentHelpers', () => {
     ).toBeCloseTo(15.5)
   })
 
+  it('calculates totals with exact decimal arithmetic', () => {
+    expect(
+      calculateTotal([
+        createPaymentItem('A', 0.1),
+        createPaymentItem('B', '0.2'),
+      ])
+    ).toBe(0.3)
+    expect(
+      calculateTotal([
+        createPaymentItem('Coffee', 4.99),
+        createPaymentItem('Tax', 0.5),
+      ])
+    ).toBe(5.49)
+  })
+
+  it('returns NaN totals for invalid amounts', () => {
+    expect(
+      calculateTotal([
+        createPaymentItem('Coffee', 4.99),
+        createPaymentItem('Broken', NaN),
+      ])
+    ).toBeNaN()
+    expect(calculateTotal([createPaymentItem('Broken', 'abc')])).toBeNaN()
+  })
+
   it('creates payment requests with sane defaults', () => {
     const request = createPaymentRequest({
       amount: 19.99,
@@ -43,7 +68,7 @@ describe('paymentHelpers', () => {
     expect(request).toEqual({
       countryCode: 'US',
       currencyCode: 'USD',
-      paymentItems: [{ label: 'Pro Plan', amount: 19.99, type: 'final' }],
+      paymentItems: [{ label: 'Pro Plan', amount: '19.99', type: 'final' }],
       supportedNetworks: [
         CommonNetworks.VISA,
         CommonNetworks.MASTERCARD,
@@ -78,6 +103,18 @@ describe('paymentHelpers', () => {
     expect(request.googlePayMerchantId).toBe('google-pay-merchant-id')
   })
 
+  it('rejects invalid amounts in created payment requests', () => {
+    expect(() => createPaymentRequest({ amount: NaN, label: 'Order' })).toThrow(
+      'finite number or a decimal string'
+    )
+    expect(() => createPaymentRequest({ amount: -1, label: 'Order' })).toThrow(
+      'must not be negative'
+    )
+    expect(() =>
+      createPaymentRequest({ amount: 1.005, label: 'Order' })
+    ).toThrow('more than 2 decimal places')
+  })
+
   it('omits undefined optional fields from created payment requests', () => {
     const request = createPaymentRequest({
       amount: 10,
@@ -114,6 +151,16 @@ describe('paymentHelpers', () => {
     expect(parseAmount('29.90')).toBeCloseTo(29.9)
   })
 
+  it('formats string amounts with currency precision', () => {
+    expect(formatAmount('100')).toBe('100.00')
+    expect(formatAmount(1.005)).toBe('1.01')
+    expect(formatAmount('-1.005')).toBe('-1.01')
+    expect(formatAmount('1.004')).toBe('1.00')
+    expect(formatAmount(1500, 'JPY')).toBe('1500')
+    expect(formatAmount('1.2345', 'KWD')).toBe('1.235')
+    expect(formatAmount(NaN)).toBe('NaN')
+  })
+
   it('checks network support using case-insensitive matching', () => {
     expect(isNetworkSupported('AMEX', ['visa', 'amex'])).toBe(true)
     expect(isNetworkSupported('discover', ['visa', 'mastercard'])).toBe(false)
diff --git a/package/src/utils/amounts.ts b/package/src/utils/amounts.ts
new file mode 100644
index 0000000..51937d0
--- /dev/null
+++ b/package/src/utils/amounts.ts
@@ -0,0 +1,250 @@
+/**
+ * Exact monetary amounts.
+ *
+ * Amounts are validated in JS and sent to native code as decimal strings
+ * scaled to the currency (`'19.90'`, `'1000'`, `'1.230'`), so they never pass
+ * through binary floating point on the way to PassKit or Google Pay.
+ *
+ * @module amounts
+ */
+
+import type { PaymentAmount, PaymentItem, PaymentRequest } from '../types'
+
+/**
+ * ISO 4217 currencies whose minor unit is not two digits.
+ */
+const CURRENCY_MINOR_UNITS: Readonly<Record<string, number>> = {
+  BIF: 0,
+  CLP: 0,
+  DJF: 0,
+  GNF: 0,
+  ISK: 0,
+  JPY: 0,
+  KMF: 0,
+  KRW: 0,
+  PYG: 0,
+  RWF: 0,
+  UGX: 0,
+  UYI: 0,
+  VND: 0,
+  VUV: 0,
+  XAF: 0,
+  XOF: 0,
+  XPF: 0,
+  BHD: 3,
+  IQD: 3,
+  JOD: 3,
+  KWD: 3,
+  LYD: 3,
+  OMR: 3,
+  TND: 3,
+  CLF: 4,
+  UYW: 4,
+}
+
+const DEFAULT_MINOR_UNITS = 2
+
+const DECIMAL_PATTERN = /^(-)?(\d+)(?:\.(\d+))?$/
+
+const ZERO = BigInt(0)
+const ONE = BigInt(1)
+const TWO = BigInt(2)
+
+/**
+ * `value = units / 10^scale`
+ */
+interface ExactDecimal {
+  units: bigint
+  scale: number
+}
+
+/**
+ * Returns the number of decimal places the currency allows (ISO 4217).
+ * Unknown codes default to 2.
+ *
+ * @example
+ * ```typescript
+ * getCurrencyMinorUnits('USD') // 2
+ * getCurrencyMinorUnits('JPY') // 0
+ * getCurrencyMinorUnits('KWD') // 3
+ * ```
+ */
+export function getCurrencyMinorUnits(currencyCode: string): number {
+  return CURRENCY_MINOR_UNITS[currencyCode.toUpperCase()] ?? DEFAULT_MINOR_UNITS
+}
+
+function powerOfTen(exponent: number): bigint {
+  return BigInt('1'.padEnd(exponent + 1, '0'))
+}
+
+function parseDecimal(amount: PaymentAmount): ExactDecimal | null {
+  let text: string
+  if (typeof amount === 'number') {
+    if (!Number.isFinite(amount)) return null
+    // Shortest round-trip form: 19.99 -> "19.99". Exponent forms such as
+    // "1e+21" or "1e-7" do not match the pattern and are rejected.
+    text = String(amount)
+  } else if (typeof amount === 'string') {
+    text = amount
+  } else {
+    return null
+  }
+
+  const match = DECIMAL_PATTERN.exec(text)
+  if (!match) return null
+
+  const [, sign, whole = '', fraction = ''] = match
+  const magnitude = BigInt(whole + fraction)
+  return { units: sign ? -magnitude : magnitude, scale: fraction.length }
+}
+
+function rescale(value: ExactDecimal, scale: number): bigint {
+  return value.units * powerOfTen(scale - value.scale)
+}
+
+function formatDecimal(units: bigint, scale: number): string {
+  const negative = units < ZERO
+  const digits = (negative ? -units : units).toString().padStart(scale + 1, '0')
+  const whole = digits.slice(0, digits.length - scale)
+  const fraction = digits.slice(digits.length - scale)
+  return (negative ? '-' : '') + whole + (scale > 0 ? `.${fraction}` : '')
+}
+
+function sum(values: ExactDecimal[]): ExactDecimal {
+  const scale = Math.max(0, ...values.map((value) => value.scale))
+  const units = values.reduce(
+    (total, value) => total + rescale(value, scale),
+    ZERO
+  )
+  return { units, scale }
+}
+
+function describeAmount(amount: unknown): string {
+  return typeof amount === 'string' ? `"${amount}"` : String(amount)
+}
+
+/**
+ * Validates an amount and returns it as a decimal string with exactly as many
+ * decimal places as the currency allows.
+ *
+ * @throws Error if the amount is not a finite number or a plain decimal
+ *   string, or has more decimal places than the currency allows.
+ *
+ * @example
+ * ```typescript
+ * normalizeAmount(19.9, 'USD')     // "19.90"
+ * normalizeAmount('1000', 'JPY')   // "1000"
+ * normalizeAmount(1.005, 'USD')    // throws: more than 2 decimal places
+ * normalizeAmount(0.1 + 0.2, 'USD') // throws: 0.30000000000000004
+ * ```
+ */
+export function normalizeAmount(
+  amount: PaymentAmount,
+  currencyCode: string,
+  label?: string
+): string {
+  const subject = label === undefined ? 'Amount' : `Amount for "${label}"`
+  const value = parseDecimal(amount)
+  if (value === null) {
+    throw new Error(
+      `${subject} must be a finite number or a decimal string like "19.99", got ${describeAmount(amount)}`
+    )
+  }
+
+  const minorUnits = getCurrencyMinorUnits(currencyCode)
+  if (value.scale <= minorUnits) {
+    return formatDecimal(rescale(value, minorUnits), minorUnits)
+  }
+
+  const divisor = powerOfTen(value.scale - minorUnits)
+  if (value.units % divisor !== ZERO) {
+    throw new Error(
+      `${subject} has more than ${minorUnits} decimal places, which ${currencyCode} allows, got ${describeAmount(amount)}`
+    )
+  }
+  return formatDecimal(value.units / divisor, minorUnits)
+}
+
+function normalizeItems(
+  items: PaymentItem[],
+  currencyCode: string
+): PaymentItem[] {
+  return items.map((item) => ({
+    ...item,
+    amount: normalizeAmount(item.amount, currencyCode, item.label),
+  }))
+}
+
+/**
+ * Validates every amount in a payment request and returns a copy whose
+ * amounts are exact decimal strings. Call it before passing a hand-built
+ * request to `HybridPaymentHandler.startPayment`; `createPaymentRequest` and
+ * `usePaymentCheckout` already do.
+ *
+ * Line items may be negative (discounts), but the total may not.
+ *
+ * @throws Error if an amount is invalid or the total is negative.
+ */
+export function normalizePaymentRequest(
+  request: PaymentRequest
+): PaymentRequest {
+  const { currencyCode } = request
+  const paymentItems = normalizeItems(request.paymentItems, currencyCode)
+
+  const total = sum(
+    paymentItems.map((item) => parseDecimal(item.amount) as ExactDecimal)
+  )
+  if (total.units < ZERO) {
+    throw new Error(
+      `Payment total must not be negative, got ${formatDecimal(total.units, total.scale)}`
+    )
+  }
+
+  return {
+    ...request,
+    paymentItems,
+    ...(request.shippingMethods && {
+      shippingMethods: normalizeItems(request.shippingMethods, currencyCode),
+    }),
+  }
+}
+
+/**
+ * Sums amounts exactly. Returns `NaN` if any amount is invalid.
+ */
+export function sumAmounts(amounts: PaymentAmount[]): number {
+  const values = amounts.map(parseDecimal)
+  if (values.some((value) => value === null)) return NaN
+
+  const total = sum(values as ExactDecimal[])
+  return Number(formatDecimal(total.units, total.scale))
+}
+
+/**
+ * Rounds an amount half away from zero to the currency's decimal places.
+ * Returns `'NaN'` if the amount is invalid.
+ */
+export function roundAmount(
+  amount: PaymentAmount,
+  currencyCode?: string
+): string {
+  const value = parseDecimal(amount)
+  if (value === null) return 'NaN'
+
+  const minorUnits =
+    currencyCode === undefined
+      ? DEFAULT_MINOR_UNITS
+      : getCurrencyMinorUnits(currencyCode)
+  if (value.scale <= minorUnits) {
+    return formatDecimal(rescale(value, minorUnits), minorUnits)
+  }
+
+  const divisor = powerOfTen(value.scale - minorUnits)
+  const remainder = value.units % divisor
+  const absoluteRemainder = remainder < ZERO ? -remainder : remainder
+  let units = value.units / divisor
+  if (absoluteRemainder * TWO >= divisor) {
+    units += value.units < ZERO ? -ONE : ONE
+  }
+  return formatDecimal(units, minorUnits)
+}
diff --git a/package/src/utils/index.ts b/package/src/utils/index.ts
index 621d829..7c5d633 100644
--- a/package/src/utils/index.ts
+++ b/package/src/utils/index.ts
@@ -3,3 +3,4 @@
  */
 
 export * from './paymentHelpers'
+export { normalizePaymentRequest } from './amounts'
diff --git a/package/src/utils/paymentHelpers.ts b/package/src/utils/paymentHelpers.ts
index 36c3689..8eeaa26 100644
--- a/package/src/utils/paymentHelpers.ts
+++ b/package/src/utils/paymentHelpers.ts
@@ -17,7 +17,13 @@
  * ```
  */
 
-import type { PaymentItem, PaymentRequest, PaymentNetwork } from '../types'
+import type {
+  PaymentAmount,
+  PaymentItem,
+  PaymentRequest,
+  PaymentNetwork,
+} from '../types'
+import { normalizePaymentRequest, roundAmount, sumAmounts } from './amounts'
 
 /**
  * Payment networks supported by both Apple Pay and Google Pay
@@ -58,19 +64,20 @@ export function sanitizePaymentRequest(
  * Creates a payment item with the specified label, amount, and type.
  *
  * @param label - Display label for the payment item
- * @param amount - Amount in the payment currency
+ * @param amount - Amount in the payment currency, as a number or a decimal
+ *   string. Validated when the payment starts.
  * @param type - Item type: 'final' for confirmed amounts, 'pending' for estimates
  * @returns A PaymentItem object
  *
  * @example
  * ```typescript
- * const item = createPaymentItem('Subscription', 29.99, 'final')
+ * const item = createPaymentItem('Subscription', '29.99', 'final')
  * const shipping = createPaymentItem('Shipping', 5.00, 'pending')
  * ```
  */
 export function createPaymentItem(
   label: string,
-  amount: number,
+  amount: PaymentAmount,
   type: 'final' | 'pending' = 'final'
 ): PaymentItem {
   return { label, amount, type }
@@ -79,6 +86,9 @@ export function createPaymentItem(
 /**
  * Calculates the total amount from an array of payment items.
  *
+ * The sum is exact decimal arithmetic, the same as native code uses, so
+ * `0.1 + 0.2` items total `0.3`. Returns `NaN` if any amount is invalid.
+ *
  * @param items - Array of payment items to sum
  * @returns Total amount
  *
@@ -86,13 +96,13 @@ export function createPaymentItem(
  * ```typescript
  * const items = [
  *   createPaymentItem('Product', 29.99),
- *   createPaymentItem('Tax', 2.40)
+ *   createPaymentItem('Tax', '2.40')
  * ]
  * const total = calculateTotal(items) // 32.39
  * ```
  */
 export function calculateTotal(items: PaymentItem[]): number {
-  return items.reduce((sum, item) => sum + item.amount, 0)
+  return sumAmounts(items.map((item) => item.amount))
 }
 
 /**
@@ -104,8 +114,12 @@ export function calculateTotal(items: PaymentItem[]): number {
  * - supportedNetworks: ['visa', 'mastercard', 'amex', 'discover']
  * - merchantCapabilities: ['3DS']
  *
+ * Amounts in the returned request are exact decimal strings
+ * (see `normalizePaymentRequest`).
+ *
  * @param options - Payment request options (amount and label required)
  * @returns Complete PaymentRequest object
+ * @throws Error if an amount is invalid for the currency
  *
  * @example
  * ```typescript
@@ -119,7 +133,7 @@ export function calculateTotal(items: PaymentItem[]): number {
  */
 export function createPaymentRequest(
   options: Partial<PaymentRequest> & {
-    amount: number
+    amount: PaymentAmount
     label: string
   }
 ): PaymentRequest {
@@ -133,30 +147,39 @@ export function createPaymentRequest(
     ...rest
   } = options
 
-  return sanitizePaymentRequest({
-    countryCode,
-    currencyCode,
-    paymentItems: [createPaymentItem(label, amount, 'final')],
-    supportedNetworks,
-    merchantCapabilities,
-    ...rest,
-  } as PaymentRequest)
+  return normalizePaymentRequest(
+    sanitizePaymentRequest({
+      countryCode,
+      currencyCode,
+      paymentItems: [createPaymentItem(label, amount, 'final')],
+      supportedNetworks,
+      merchantCapabilities,
+      ...rest,
+    } as PaymentRequest)
+  )
 }
 
 /**
- * Formats an amount to 2 decimal places.
+ * Formats an amount with the currency's number of decimal places (2 when no
+ * currency is given), rounding half away from zero.
  *
- * @param amount - Numeric amount to format
- * @returns Formatted amount string
+ * @param amount - Amount to format, as a number or a decimal string
+ * @param currencyCode - ISO 4217 currency code
+ * @returns Formatted amount string, or `'NaN'` if the amount is invalid
  *
  * @example
  * ```typescript
  * formatAmount(29.9) // "29.90"
- * formatAmount(100) // "100.00"
+ * formatAmount('100') // "100.00"
+ * formatAmount(1.005) // "1.01"
+ * formatAmount(1500, 'JPY') // "1500"
  * ```
  */
-export function formatAmount(amount: number): string {
-  return amount.toFixed(2)
+export function formatAmount(
+  amount: PaymentAmount,
+  currencyCode?: string
+): string {
+  return roundAmount(amount, currencyCode)
 }
 
 /**