Skip to main content

Refunds from merchant servers

This is a draft specification for preview review. It does not announce production availability. Availability will be updated after advance sharing with JPYC EX.

Registration and approval​

Generate a P-256 key inside the merchant server, using Node.js generateKeyPairSync('ec', { namedCurve: 'prime256v1' }), for example. Keep the private key in the merchant's secret store or KMS/HSM. Never send it to STBL Pay. Register the uncompressed public key 0x04 || X || Y in the store detail's merchant server refunds section (Setup for online stores, Settings for in-person QR stores). The owner approves a delegation with a passkey, binding the public key, refund-only permission, per-refund cap, wallet, epoch and chainId. There are at most 10 non-revoked members per store, including pending members. An omitted cap means unlimited; "0" disables refunds. The stblpay_machine_ key followed by 43 base64url characters is displayed only at issuance or rotation. Payment API keys cannot be substituted.

Delegation does not permit standalone wallet upgrades. On a supported wallet, when the service configuration and Registry conditions are met, it may upgrade to the Registry-designated implementation together with the refund. This does not authorize upgrading to an arbitrary implementation. Approval itself only updates the delegation; it does not submit a refund or a wallet upgrade.

Each refund requires both the machine signature and STBL Pay’s co-signature. STBL Pay can refuse to co-sign after its checks, but cannot transfer funds without the machine signature.

API flow​

Attach an HTTP signature to each request. amountJpy is a decimal string in yen, with up to six decimal places. Avoid floating-point conversion.

  1. Check GET /payment_intents/{paymentIntentId}/refundable for executable amount and blockers.
  2. Send {"amountJpy":"100"} to POST /payment_intents/{paymentIntentId}/refunds/prepare.
  3. The returned challenge is the digest to sign, and rpId is used to build authenticatorData. Sign it following Challenge signature, then send stagedOpId and assertion to POST /payment_intents/{paymentIntentId}/refunds/submit.
  4. Save the accepted refundId. Query GET /refunds/{refundId} or GET /payment_intents/{paymentIntentId}/refunds. Acceptance is not completion and carries no transaction hash.

The recipient is fixed to the original payer and is omitted from prepare. The owner and all machines share one serial operation slot per merchant wallet, including operations from other stores and redemption. Other stores' resources return 404. Accepted refunds within the same store are readable; unconsumed preparations are visible and cancelable only by their machine.

Recovery​

  • Lost prepare response: check the refundable amount and inspect ownStaged, which can refer to another payment or process using the same machine. Check its paymentIntentId, stagedOpId and the process that created it, and coordinate with any process still working on it. Use DELETE /staged_operations/{stagedOpId} only for an unconsumed preparation you intentionally abandon, then prepare again.
  • Lost submit response: resubmit the refund using the same stagedOpId and assertion with a fresh HTTP nonce, timestamp and signature. If already accepted, the retry returns the same refundId and walletOperationId. After recovery, query that refundId or the payment’s refund list for the result as usual. Do not prepare a new refund.
  • Missing Webhook: reconcile by looking up the refund. refund.confirmed means completion; refund.failed means failure. The original payment stays settled.
  • HTTP419 auth/clock_skew: adjust the clock offset using details.serverTime (epoch milliseconds) in the response and retry once with a fresh nonce, timestamp and HTTP signature. Investigate persistent clock errors.

Funds and revocation​

refundableNowJpy is constrained by the ledger, on-chain backing and wallet balance. executableJpy is the minimum of that amount and delegationCapJpy, or "0" when blocked. Unavailable observations are not estimated. See refund funds. Store and payment restrictions are backend checks; the contract does not identify stores or payments.

Revocation prevents new acceptance. Cap replacement and API key rotation apply the new cap or key to subsequent acceptance. They do not guarantee cancellation of already accepted operations. On-chain revocation of old delegations is not supported. Delegation does not permit redemption, arbitrary recipients, standalone wallet upgrades or human staff access. A disabled store rejects new prepare/submit requests while allowing queries, cancellation of the machine's own preparation, and owner revocation/key rotation.