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.
- Check
GET /payment_intents/{paymentIntentId}/refundablefor executable amount and blockers. - Send
{"amountJpy":"100"}toPOST /payment_intents/{paymentIntentId}/refunds/prepare. - The returned
challengeis the digest to sign, andrpIdis used to buildauthenticatorData. Sign it following Challenge signature, then sendstagedOpIdandassertiontoPOST /payment_intents/{paymentIntentId}/refunds/submit. - Save the accepted
refundId. QueryGET /refunds/{refundId}orGET /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 itspaymentIntentId,stagedOpIdand the process that created it, and coordinate with any process still working on it. UseDELETE /staged_operations/{stagedOpId}only for an unconsumed preparation you intentionally abandon, then prepare again. - Lost submit response: resubmit the refund using the same
stagedOpIdand assertion with a fresh HTTP nonce, timestamp and signature. If already accepted, the retry returns the samerefundIdandwalletOperationId. After recovery, query thatrefundIdor 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.confirmedmeans completion;refund.failedmeans failure. The original payment stayssettled. - HTTP419
auth/clock_skew: adjust the clock offset usingdetails.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.