FAQ
Do I need to build a checkout screen too?
No. The STBLpay checkout page handles payment confirmation and passkey approval. Example: the merchant builds only the "Pay" button, and the screen after it is pressed belongs to STBLpay.
Is the payment complete when the create payment API returns?
No. The API has only created a payment intent (a record of the payment request), and the status at this point is created (waiting for signature). Confirm completion with the Webhook payment.settled, or with settled from a status lookup. Be ready to check with a status lookup too, in case a notification does not arrive. Example: do not provide the goods when you receive the create API response. Wait until you confirm settled. See Completion check.
Can I choose orderId freely?
orderId identifies each payment attempt (up to 128 characters). Assign values that are unique across the whole merchant. Creating a payment again with the same orderId returns the existing payment, so use the same value when you resend a request (after a timeout or a double click). To let the buyer pay again after failed, expired, or canceled, create the payment with a new orderId (Idempotency). You can use your own order number as is only if you never create another payment attempt for the same order. If you do, keep track of which payment attempts belong to each order on your side.
What is a top-level navigation?
It means moving to checkoutUrl with the whole page, like an ordinary link. Do not put it in an iframe or popup. Example: navigate with window.location.href = checkoutUrl. This makes sure passkey approval happens on the right page and prevents the page from being swapped for a fake screen. The glossary also defines the term.
When does the buyer return to the merchant site after payment?
When the payment reaches a terminal state, the STBLpay checkout page shows a button back to the merchant. Whether the payment succeeded, failed, expired, was canceled, or ended in nonce_conflict, the button goes to the returnUrl you specified when creating the payment. If you did not specify returnUrl, no button is shown and the page says "You may close this tab" (このタブは閉じていただいてかまいません). Example: on the return page, show "Checking" and switch based on the order status on the server side. The return does not wait for the Webhook, so the buyer may return before the order is updated. Some buyers do not return. If a merchant suspension aborts the payment, no button is shown even if you specified returnUrl, and the page says "Close this screen and place the order again from the store's page." (この画面を閉じて、お店のページからご注文をやり直してください。) Do not use the buyer's return as the basis for success.
Do I need an SDK?
No. We do not provide a merchant integration SDK. After you create the payment, navigate to checkoutUrl. See How to integrate today.
Can I resend a request to create a payment?
Yes. The same store gets the existing payment back for the same orderId. Do not generate a new number on every communication failure. Retrying does not update the amount or deadline of an existing payment. The payment that comes back may already be terminal (it goes no further), so check status in the response before sending the buyer to checkoutUrl. How to handle each status is in Idempotency.
Is the amount a number?
No. API amounts are strings in yen, and Webhook amounts are strings too. In the payment.failed, payment.canceled, and payment.expired notifications, fee_jpy and net_received_jpy are "0" (Amounts). The status lookup API does not return the amount or the fee.
Can I provide the goods once it is signed?
No. signed and deposit_confirmed are in-progress statuses. Confirm success on the server, then provide the goods exactly once.
Which Webhooks are delivered?
Four kinds: success, failure, cancellation, and expiry. For nonce_conflict, you need to run a status lookup and investigate. Deduplicate by the id in the signature-verified body. A test notification sent from the merchant console has the payment.settled form with test: true in the body. Return 2xx without changing any order (Test notifications). The body is defined in WebhookEvent and TestWebhookEvent in the OpenAPI specification.
Can a payment succeed after cancellation?
No. The API's canceled is a terminal state, so the payment does not succeed. Distinguish this from the case where STBLpay cannot observe the cancellation of a reservation at the issuer and the payment is still issue_pending.
When do I close an order that never comes back?
Do not use a fixed elapsed time. Judge by whether a status lookup or a Webhook shows a terminal status such as expired (see Operation deadline and deposit deadline). If you close your own order first, detect any later success and route it to operational handling.
Can I use a refund API?
No. There is no refund API that you can call from the merchant server. The owner makes refunds from the Transaction details (取引の詳細) screen of the merchant console and approves them with a passkey. The refund destination is fixed to the original payer. See Scope of refunds.
Is the payment ID a secret?
No. Apply your own authentication and authorization when you let people view your own orders.
Is there an environment for trying my integration?
Yes, the Sandbox. The items to check are in Test scenarios.