HyoNovaDocumentation

Idempotency in payments

Every way HyoNova Commerce makes repeated requests, retried webhooks and concurrent workers safe — keys, unique records, versions and once-only notifications.

Requires setupBuilt, but works only after a supporting service is configured for your workspace.ReferenceFor: Developers, IT & securityLast updated: Introduced:
On this page

A payment method appears only after HyoNova has set up its payment provider.

Payments are retried by browsers, networks, providers and workers. HyoNova Commerce is built so that doing something twice has the same effect as doing it once.

Request keys#

Money actions that a client may retry send an Idempotency-Key header of 16 to 100 characters (letters, digits, _ . : -). A missing or malformed key is refused with IDEMPOTENCY_KEY_REQUIRED.

ActionUnique perRepeat returns
Start a checkoutCompany + keyThe checkout already created
Confirm a bank paymentCompany + keyThe payment already recorded
Request a refundCompany + keyThe refund already requested (a key reused for another payment is refused)

Unique records#

GuardEffect
One open checkout per companyA second checkout while one is open is refused with CHECKOUT_IN_PROGRESS
Provider event key (provider, event id)A retried webhook is a duplicate
Provider payment, order, invoice and refund referencesThe same provider object is never recorded twice
One open refund per paymentREFUND_ALREADY_EXISTS
Billing timeline key per companyThe same change is never logged — or notified — twice
One email per event and recipientA billing notice is never emailed twice to the same person
Invoice numbersTaken under a row lock: never skipped, never repeated

Calls to providers#

HyoNova passes its own ids as idempotency keys to providers — the checkout id for a checkout, the refund id for a refund, and <subscription>:<version>-style keys for subscription changes, cancellations and resumptions. Outbound calls are retried only when they are safe to repeat: reads, or writes the provider deduplicates by key.

Versions#

Subscription, invoice, billing profile, provider and routing changes carry the version the caller last read. A stale version is refused (SUBSCRIPTION_CONFLICT or RESOURCE_VERSION_CONFLICT) so two people never overwrite each other.

Workers#

Billing maintenance runs in one worker at a time (a database advisory lock) and at most once a minute; every change it makes uses the same timeline keys, so a repeated run changes nothing.

Payment architecture

How HyoNova Commerce works — one commerce core over payment provider adapters, capabilities instead of provider names, routing with a safe fallback, checkout, subscriptions, invoices and security.

Payment webhooks

How HyoNova receives payment provider webhooks — raw body, signature verification, deduplication, ordering, atomic processing, and which HTTP answers make providers retry.

API conventions

The conventions HyoNova APIs follow — base URL, JSON errors, request IDs, HTTP status codes, cursor pagination, idempotency keys and rate limits — as the Mail API applies them.

↑↓ to navigate · Enter to open · Esc to close