[shihweilo]

Four corrections found by checking the SDK against the current TapPay
documentation. Two are defects introduced in 0.7.0. That version was tagged
but never published to PyPI, so no released version ever exposed them.

Fixes

Models.Currencies listed 11 currencies TapPay does not accept

0.7.0 shipped JPY, GBP, AUD, EUR, CNY, KRW, SGD, THB, PHP,
IDR and VND. None are documented; they were added on assumption rather than
from the docs. They autocompleted in an IDE and looked sanctioned, so they would
eventually have reached production and been rejected at the API.

TapPay documents exactly four, each tied to the acquirer on your merchant
account:

Currency	Acquirer
TWD	Most acquirers
HKD	Bank of China
MYR	RAZER PAY
USD	Global Payments

Removed rather than deprecated — keeping them would keep suggesting values that
fail. Plain currency strings still pass through, so the enum narrows what the
SDK suggests, not what a caller may send.

raise_on_error=True raised on normal end-of-pagination

The Record API answers status: 2 for "end of list, no more records under the
given filter" — how paging terminates. 0.7.0 treated every non-zero status as a
failure, so paging to the end of any query raised TapPayError.

Benign statuses are now scoped per endpoint via BENIGN_STATUSES. 2 is benign
for /tpc/transaction/query only and still raises everywhere else, which is
covered by a test asserting the same status raises on a payment endpoint.

Full refunds were unreachable

refund() required amount, but TapPay documents it as needed "only for
partial refund" — omitting it refunds the whole transaction. There was no way
to express a full refund without already knowing the exact amount.

amount is now optional and dropped from the request when None. It uses
is not None rather than a truthiness check: 0 is falsy but means a
zero-value partial refund, and a truthy test would silently turn that into
refunding the entire transaction.

client.refund("rec_trade_id")            # full refund
client.refund("rec_trade_id", 100)       # partial

Default read timeout was below TapPay's documented minimum

It was 27.0s, taken from a generic requests convention. TapPay documents 30s
because banks take longer at peak, so the shorter value could report a timeout
for a transaction that actually succeeded — the worst failure mode for a payment
client. DEFAULT_TIMEOUT is now (3.05, 30.0).

Verification

102 tests, coverage stays at 100%. ruff and mypy clean. Verified in a clean
worktree, and end-to-end:

currencies      : ['TWD', 'HKD', 'MYR', 'USD']
default timeout : (3.05, 30.0)
full refund     : {'rec_trade_id': 'rec'}
partial refund  : {'rec_trade_id': 'rec', 'amount': 250}
record status 2 : returns normally
cap    status 2 : raises TapPayError(status=2)

Scope

Checked against the Backend, Advanced Features and Reference pages as of
2026-09-09. TapPay publishes no API changelog, so these are differences observed
against current documentation, not a dated diff.

Deferred to 0.8.0 and recorded in CHANGELOG.md: pay_by_token accepts no
cardholder (whose phone_number and email are required for 3D-secure token
payments); CardHolderData is missing name_en, phone_number_country_code,
member_id and bank_member_id and validates none of the documented field
lengths; filters and details are required by this SDK but optional in the
API; and nine documented endpoints remain unimplemented, including
reconciliation, card metadata and update-cardholder.

Note on v0.7.0

That tag is on master and carries the fabricated currency list. It never
reached PyPI so nobody can have installed it, but it is a public artifact
advertising currencies TapPay rejects. Worth deleting it or tagging v0.7.1
promptly behind it.

🤖 Generated with Claude Code