Skip to main content

State transitions and deadlines

This page summarizes the transition conditions that merchants use to make decisions. It does not cover worker locking or retry details.

Follow the diagram from top to bottom, answering each branch question with yes or no. Next to each arrow, the diagram shows whose action moves the payment forward.

Flowchart of payment status transitions. Starting from created, it branches on buyer approval, whether the balance is enough, the deposit, wallet creation and whether the send succeeded, and ends in settled, failed, nonce_conflict, expired or canceled.Normal flowWebhook is sentNo Webhook (check status)Buyercancels on My PagecanceledCanceled by buyerMerchantcreates via APIcreatedCreated, awaiting approvalBuyerapproved?NoexpiredNot approved in timeYesBuyerapproves with passkeysignedSignature receivedexpiredDeadline reachedBalanceenough?Yes: use balanceSTBLpayconfirmsNoBuyergoes to JPYC EXissue_pendingStarted, awaiting depositEnough fundsby the deadline?NoexpiredPast deposit deadlineYesBuyertransfers,JPYC EXissuesExisting balance counts toward itdeposit_confirmedFunds confirmedfailedFailed before sendingnonce_conflictOutcome unknownWalletcreated?NodeployingCreating walletSTBLpaycreates, returnsfailedCreation failedYesSTBLpaysends JPYCexecutingChecking send resultSendsucceeded?NofailedSend failednonce_conflictOutcome unknownYessettledPayment completedFlowchart of payment status transitions. Starting from created, it branches on buyer approval, whether the balance is enough, the deposit, wallet creation and whether the send succeeded, and ends in settled, failed, nonce_conflict, expired or canceled.createdCreated by merchantBuyerapproved?expiredNot approvedYesBuyersignedApproved with passkeyCexpiredTimed outBalanceenough?Yes: use balance→ go to mark AANoBuyerissue_pendingWent to JPYC EXCEnough fundsby the deadline?expiredDeposit expiredYesBuyertransfersJPYC EXissuesBalance counts toward itdeposit_confirmedFunds confirmedABfailedNot sentnonce_conflictUnknownWalletcreated?deployingThen go to mark BOn failure: failedBYesSTBLpayexecutingSTBLpay sends JPYCSendsucceeded?failedSend failednonce_conflictUnknownYessettledPayment completedBuyercancels on My PagecanceledCanceled by buyerCFrom signed, or issue_pending before the deposit,a buyer cancellation leads to canceled.Normal flowWebhook is sentNo Webhook (check status)AContinues at the same mark

Normal flow​

Depending on whether the buyer's JPYC balance is sufficient, the in-progress statuses take one of two paths. Both end in settled.

When the balance is sufficient

StatusWhat happenedWho acted (screen)
createdThe payment was created. Waiting for a signatureMerchant server
signedThe payment operation was signedBuyer (approves with a passkey on the checkout page)
deposit_confirmedConfirmed that the balance covers the paymentSTBLpay
deployingCreating wallets. This happens only the first time; when done, returns to deposit_confirmedSTBLpay
executingExecuting the transfer and waiting for the resultSTBLpay
settledThe transfer succeeded and JPYC arrived in the merchant's receiving wallet-

When a bank transfer is needed

StatusWhat happenedWho acted (screen)
createdThe payment was created. Waiting for a signatureMerchant server
signedThe payment operation was signedBuyer (approves with a passkey on the checkout page)
issue_pendingThe buyer went on to the JPYC EX procedure (STBLpay received the reservation-start notification). Waiting for the deposit. STBLpay has not verified whether the JPYC EX procedure is completeBuyer (from the checkout page to JPYC EX)
deposit_confirmedConfirmed that the issued JPYC arrived and the payable amount is availableThe buyer makes the bank transfer and JPYC EX issues. STBLpay confirms
deploying onwardSame as when the balance is sufficientSTBLpay

A Webhook arrives only when the payment reaches a terminal status such as settled. However, among terminal statuses, no Webhook arrives for nonce_conflict. Check in-progress statuses and nonce_conflict with a status lookup. When a bank transfer is needed, the payment waits for the buyer's transfer, so it may stay in issue_pending for a while. This is not a failure.

Transition list​

From statusConditionTo status
createdA signature was receivedsigned
createdThe operation deadline was reachedexpired
signedA bank transfer is needed, and the checkout page's reservation-start notification was received (the outcome of the JPYC EX procedure is not checked)issue_pending
signedSTBLpay confirmed that the balance is sufficientdeposit_confirmed
signedThe operation deadline was reachedexpired
signedThe buyer canceled on My Page (マイページ)canceled
issue_pendingThe payable amount became available within the deadline (the deposit of issued JPYC, or its sum with the current balance)deposit_confirmed
issue_pendingThe destination of the deposit from JPYC EX does not match the sender of the payment operation the buyer signed (the buyer's wallet used for this payment)failed
issue_pendingThe deposit deadline and the confirmation-wait grace period have passedexpired
issue_pendingThe buyer canceled on My Page (マイページ) before the deposit was confirmedcanceled
deposit_confirmedThe wallets have not been created yetdeploying
deposit_confirmedSTBLpay started executionexecuting
deposit_confirmedBefore execution, an unrecoverable failure was determined, or retries were used upfailed
deposit_confirmedThe transfer result cannot be determinednonce_conflict
deposit_confirmedThe transfer turns out to have already been executed, and it succeededsettled
deployingPreparation of the two wallets finisheddeposit_confirmed
deployingIt failed, or the attempt limit was reachedfailed
executingExecution succeededsettled
executingIt failed, or retries were used upfailed
executingThe transfer result cannot be determinednonce_conflict

The diagram and the list omit or combine the following three items.

  • The transition from issue_pending to failed (deposit destination mismatch) is a safeguard against inconsistent stored data and does not occur in normal operation. It is therefore omitted from the diagram.
  • When a merchant is suspended, payments that have not yet started the transfer become failed (failed_reason is merchant_suspended). This is omitted from the diagram and the list. See Merchant suspension for details.
  • The direct transition from deposit_confirmed to settled (when the transfer turns out to have already been executed and succeeded) is in the list but omitted from the diagram.

deploying and executing may stay in the same status during confirmation or temporary failures. A payment cannot go directly from deploying to executing. There are no transitions out of a terminal status.

Deposits and balance payments​

For the bank transfer path, STBLpay checks the destination, sender (the JPYC issuer), chain, and time of each arriving deposit. Then, if the available balance of the buyer's wallet (the current balance plus the deposit) covers the payment amount, the payment moves to deposit_confirmed. The new deposit alone does not need to reach the payment amount. A deposit whose sender is not the issuer is not counted. The payment stays in issue_pending, and if the amount is not available by the deadline, it becomes expired. A deposit is detected only after it can no longer be reversed (Technical details).

For example, suppose a buyer with a ¥1,000 balance makes a ¥3,500 payment and has ¥3,000 issued to cover the shortfall. The sum of the balance and the deposit, ¥4,000, covers the payment amount, so the payment moves to deposit_confirmed.

A balance payment moves from signed to deposit_confirmed without waiting for a deposit to be detected. STBLpay checks periodically whether the balance is sufficient, so the transition may come a little after approval, not immediately. STBLpay prevents the same balance from being applied to multiple payments.

Operation deadline and deposit deadline​

  • created and signed before the reservation starts expire at checkoutExpiresAt. A payment never stays in these statuses forever.
  • When the reservation-start notification is first accepted, the deposit deadline is fixed as the issuance reservation deadline plus a 14-day buffer. The create response, the status lookup, and Webhooks do not include the deposit deadline. To find out the exact date and time of the deposit deadline, ask the contact.
  • issue_pending expires when no matching deposit is found even after the deposit deadline plus the confirmation-wait grace period. Whether a deposit is within the deadline is judged by the block time.
  • A deposit that arrived within the deadline is applied to the payment even if it is detected after the deadline. The grace period for this is the "confirmation-wait grace period" above.

If you specify the optional merchantExpiresAt, the earlier of the deposit deadline and the specified value becomes the deposit deadline. The operation deadline does not become shorter (you can only specify a time more than 3 days after creation, and the operation deadline is shorter than that). If omitted, the server's deadline is used as is. A value that expires within 3 days of creation is rejected. Re-creating with the same orderId cannot overwrite the specified value.

The deposit deadline is separate from the execution deadline of the payment operation the buyer signed. A merchant-specified deadline does not shorten the execution deadline (Technical details).

Cancellation​

Only the buyer can cancel a payment. The buyer approves with a passkey and cancels on STBLpay's My Page (マイページ). A payment can be canceled in signed and in issue_pending before the deposit is confirmed. There is no way for the merchant or STBLpay to cancel. When a payment is canceled, a payment.canceled Webhook is sent to the merchant. Do not equate the issuer's reservation cancellation with STBLpay's canceled.

Technical details​

These are the blockchain-side names for things described in plain terms above. Merchants do not need to handle them in their implementation. Use them when contacting support, for example.

  • nonce: A sequence number attached to operations issued by a wallet. The same number can be used only once. A payment becomes nonce_conflict when the transfer result cannot be determined and the confirmation limit is reached without identifying the outcome of the operation. This includes not only the case where it was confirmed that the number was used, but also the case where failures to read the number continued up to the limit.
  • UserOperation: The unit of operation for payment that the buyer signs. The "payment operation" in the text refers to this.
  • validUntil: The execution deadline of a signed UserOperation. It is determined separately from the deposit deadline and is not shortened by a merchant-specified deadline.
  • revert: When an operation sent to the blockchain is rejected partway through execution and has no effect. It is one of the reasons a payment becomes failed.
  • Deploy: Creating a wallet on the blockchain. For the first payment, the buyer's wallet and the merchant's receiving wallet are needed, and the status passes through deploying. "Creating wallets" in the text refers to this.
  • 64 blocks (finality): When 64 blocks have been added after the block containing the deposit, it is treated as no longer reversible. This state is called finality. A deposit is detected only after it reaches this state, so the payment stays in issue_pending meanwhile.
  • minter: An address with the authority to issue JPYC. In bank transfer reconciliation, STBLpay checks whether the sender matches the issuer's minter.
  • sender: The address of the wallet that issues the UserOperation signed by the buyer (the buyer's AA Wallet used for this payment). If the destination of a deposit from JPYC EX does not match it, the payment becomes failed (this does not occur in normal operation).
  • Transfer: An event that records a movement of JPYC. Deposit detection is done by watching this record.
  • txHash: The transaction number on the blockchain. Use it when contacting support.