# Stripe Payment Integration Help ## Overview Stripe payment integration connects your own Stripe account to UnlockOS. Once connected, you can accept card, Apple Pay / Google Pay, and PayPay payments for bookings, check-ins, extensions, and membership sign-ups. Payouts go from Stripe directly to your own bank account. UnlockOS never holds your funds. > **Card details never pass through UnlockOS.** The card number, expiry date, and security code your guests type go straight from Stripe's own input form to Stripe. They never reach UnlockOS servers or the admin console, and they are never stored. See "How card data flows" below. --- ## How to Access Connection Settings → **Stripe Payment System** (`/stripe-connection`) Registering and deleting API keys requires organization owner or platform admin permission. --- ## Features ## Feature 1: Register API keys Enter the values from **Developers → API keys** in your Stripe Dashboard ([dashboard.stripe.com](https://dashboard.stripe.com/apikeys)). | Field | Where to find it | Notes | |-------|-----------------|-------| | Publishable Key | Stripe Dashboard → API keys | `pk_test_...` / `pk_live_...` | | Secret Key | Same page (click "Reveal") | `sk_test_...` / `sk_live_...` | | Webhook Secret (optional) | Stripe Dashboard → Webhooks | `whsec_...` | | Currency | — | JPY for Japan | The secret key is never displayed again after saving. If you need it later, issue a new key in Stripe and register it again rather than trying to reveal the stored one. ## Feature 2: Verify the connection After saving, use the **Verify** button to confirm connectivity to the Stripe API. On success the status changes to "Connected" and the last verification time is recorded. Do not start taking payments while the status still reads "Configured (unverified)" — a mistyped key shows up in this check. ## Feature 3: Switch between test and live mode Test and live keys are stored separately. The radio buttons on the page decide which pair is actually used for payments. - If both key pairs are already registered, switching mode does not require re-entering keys - Switch to live mode (`pk_live_...` / `sk_live_...`) before you go live - If you launch while still in test mode, guest payments will not actually settle ## Feature 4: Register the webhook secret Configuring a webhook lets UnlockOS receive the settled payment result (success, failure, refund) from Stripe. Results are not lost even if the guest closes their browser mid-payment. ## Feature 5: Get test API keys A common misunderstanding is "I can test by registering my live keys and just flipping this screen to test mode." In reality, you must **switch the Stripe Dashboard itself to test mode (sandbox) first**, then grab the keys for that mode. 1. Log in at [dashboard.stripe.com](https://dashboard.stripe.com) 2. Turn on the **Test mode / Sandbox** toggle in the top-right corner (or sidebar). You can also go straight to [dashboard.stripe.com/test/apikeys](https://dashboard.stripe.com/test/apikeys) to land on the same screen 3. Open **Developers → API keys** 4. Copy the `pk_test_...` (publishable key) and `sk_test_...` (secret key — click "Reveal" to see it) 5. Paste them into the **test mode** fields on this screen and save Stripe manages test and live keys as completely separate objects. - A payment made with a test key never charges a real card (it only works with the test card numbers below) - A payment made with a live key charges a real card. Test card numbers do not work against a live key The "Test mode / Live mode" radio buttons on this UnlockOS screen are **a switch that picks which of the two already-registered key pairs is used for the next payment** — they do not convert a key from one mode to the other. Always register a test key (`pk_test_...` / `sk_test_...`) in the test fields and a live key (`pk_live_...` / `sk_live_...`) in the live fields. For test card numbers (such as `4242 4242 4242 4242`), see Stripe's own testing page. → [Stripe docs: Testing cards](https://docs.stripe.com/testing) ## Feature 6: Enable Apple Pay / Google Pay (register payment method domains) Because UnlockOS connects each facility's own Stripe account (bring-your-own keys), registering "payment method domains" so Apple Pay / Google Pay appear on the booking and payment screens must be done **in your own Stripe account, not by UnlockOS**. ### Where to register Stripe Dashboard → Settings → **Payment method domains** Direct link: [dashboard.stripe.com/settings/payment_method_domains](https://dashboard.stripe.com/settings/payment_method_domains) Use "Add a new domain" to register each domain where a payment screen appears, one at a time. For Apple Pay, Stripe handles the Apple-side merchant registration (creating the Apple Merchant ID, etc.) on your behalf — no extra step is needed on the facility side. ### Domains you need to register Register only the domains where a Stripe payment form (card fields, Apple Pay / Google Pay buttons) is actually rendered. | Domain | Screen | |--------|--------| | `booking.unlockos.io` | Payment at booking | | `member.unlockos.io` | Membership sign-up and ticket book purchase | | `checkin.unlockos.io` | Payment at check-in and extension | | `locker.unlockos.io` | Locker payment | The embeddable snippet (a booking form placed on your own website) does not currently render a Stripe payment form inside that page. The four domains above are the current scope for registration. ### Test mode and live mode are registered separately Stripe manages payment method domains separately for the live environment and the test environment (sandbox). - **Registering a domain in the live environment automatically also registers it in the test environment (sandbox)** - **Registering a domain only in the test environment does not carry over to the live environment.** Before you go live, be sure to also register the same domain in the live environment ### What happens if you don't register On a domain that isn't registered, the Apple Pay / Google Pay button simply does not appear. Card payments (the ordinary card entry that uses the keys registered under Feature 1–3) are unaffected. Guests are not left unable to pay — they just don't see the wallet payment option. ### Google Pay also requires domain registration There is a common assumption that "only Apple Pay needs to be registered." Stripe's own documentation states, in the Google Pay guide, that you must register every web domain where the Google Pay button appears. The steps above apply equally to both Apple Pay and Google Pay. ### Known limitation: Apple Pay does not work inside LINE's in-app browser When a guest opens a booking/payment link from a LINE chat, it opens inside LINE's in-app browser, and Apple Pay JS does not work there because it requires Safari. Card payments and PayPay work as usual. When you share links through LINE, let guests know Apple Pay may not be selectable there. --- ## How card data flows A payment through the Stripe integration is processed in this order. 1. UnlockOS calculates the amount and asks Stripe to create the payment (only the amount and currency are sent) 2. **Stripe's own input form** is displayed on the guest's screen 3. The card number, expiry date, and security code the guest enters go **directly from that form to Stripe** 4. UnlockOS receives back only Stripe's identifiers (payment ID, payment method ID) and display data such as the card brand and last four digits In other words, the card number, expiry date, and security code are **neither transmitted through nor stored by** UnlockOS servers. When a guest saves a card for later, it is saved at Stripe — UnlockOS only handles the Stripe payment method ID. This is why the declaration described below counts as "not holding card data". --- ## Answering Stripe's security measures declaration Businesses accepting online card payments in Japan must submit a declaration of security measures to Stripe, based on the checklist published by the Japan Consumer Credit Association's council on credit transaction security. The following covers how facilities using UnlockOS should complete each field. > **The declaration is submitted by you, the merchant.** What follows are facts about how UnlockOS is implemented. The final wording and responsibility for the declaration rest with your facility. If you also take bookings through channels other than UnlockOS (a separate cart on your own website, manually keyed card details from phone bookings), include the measures for those channels as well. ## Filling in the outsourcing section UnlockOS is the contractor that provides your booking and payment screens (the ASP cart) on your behalf. Select **委託先企業 (Contractor)** for the first question. | Field | What to enter | |-------|--------------| | Who performs security measures on your behalf? | Select **委託先企業 (Contractor)** | | Contractor name (委託先企業名) | `ブロックチェーンロック株式会社（UnlockOS）` / Blockchain Lock Inc. (UnlockOS) | | ASP cart provider name (ASP カート事業者名) | `ブロックチェーンロック株式会社（UnlockOS）` / Blockchain Lock Inc. (UnlockOS) | | QSA that performed the PCI DSS assessment | `適用外` (Not applicable) | ### Why the contractor and ASP cart provider are the same company UnlockOS is developed and operated by Blockchain Lock Inc. The provider of the booking and payment cart and the contractor responsible for security measures are the same entity, so the same company name goes in both fields. If the field allows more detail, you can expand it like this: > Blockchain Lock Inc. (UnlockOS) — provides the booking and payment screens. Card details are entered into and held by Stripe Japan Inc.; neither those screens nor the contractor's servers hold card data. ### Why the QSA field is "Not applicable" This field asks for the QSA that assessed the contractor or ASP cart provider, where such an assessment is required. Stripe's own guidance states that you should enter 適用外 (not applicable) when neither party is required to be audited. UnlockOS does not store, process, or transmit card data (see "How card data flows" above), so it has not undergone — and is not required to undergo — a PCI DSS assessment by a QSA. `適用外` is therefore the correct entry. Stripe itself, which does handle the card data, is certified at the highest PCI DSS level (Service Provider Level 1). That is managed on Stripe's side and does not belong in this field. ## Choosing login security measures This section states that at least one measure must be implemented. Guest booking and member apps in UnlockOS **use no passwords at all** — every login is authenticated with a six-digit one-time password (OTP) sent to the user's email address. Here is how each option maps to what UnlockOS actually implements. | Option | UnlockOS implementation | Recommendation | |--------|------------------------|----------------| | Access restriction from suspicious IP addresses | Not implemented | Leave unchecked | | Two-step or multi-factor authentication for identity verification | Every login uses a single-use six-digit email OTP. No passwords exist | Your call (see below) | | Verification of personal details at registration (name, address, phone, email) | Name, email, and phone number are collected at booking. The email address is proven reachable by the OTP. Address collection, ID document upload, and SMS phone-number verification can be added through the facility's form settings | **Check this** | | Login attempt limits and throttling | The auth platform applies per-IP limits on login attempts and OTP verifications, a minimum interval between OTP resends, and OTP expiry as standard | **Check this** | | Email / SMS notification on login or account changes | Because every login sends an OTP email to the account owner, a third party attempting to log in triggers a message to the real owner. However, no separate "you have logged in" notification is sent afterwards | Your call (see below) | | Behavioral analysis | Not implemented as a login measure | Leave unchecked | | Device fingerprinting | Not implemented | Leave unchecked | | Other measures | Passwordless authentication — no password is ever stored | Recommended to describe | | Not applicable: there is no member login | The guest booking and member apps do have login | Leave unchecked (see exception below) | ### The minimum you can declare If you are unsure, checking these two satisfies the "at least one" requirement, and both are standard UnlockOS behavior. - Verification of personal details at registration (name, address, phone, email) - Login attempt limits and throttling ### Should you check "two-step or multi-factor authentication"? Opinions differ on this one. - In favor: the guideline lists "one-time password" among its example measures, and UnlockOS logins are performed with nothing but a one-time password - Against: UnlockOS has no password, so an OTP on its own is a single factor (being able to receive the email). It is not literally "two-step" If you want to be precise, select **"Other measures"** instead and describe it as `No password is stored; every login is authenticated with a one-time password sent by email`. Not storing passwords is itself a defensible measure — password reuse and credential-stuffing takeovers cannot occur by construction. ### Should you check "email / SMS notification on login"? Also a judgment call. In practice, a third party trying to log in causes an OTP email to arrive in the real owner's inbox, so the owner does find out. That said, this is an authentication step rather than a notification, and no follow-up "you logged in" email is sent. If you want to state this accurately, describe it under "Other measures". ### When you can select "Not applicable: there is no member login" Facilities that operate only through the front desk or a kiosk terminal — with no guest booking app, no member app, and no booking screen embedded in their own website — have no guest login screen at all, so this option applies. It does not apply if you use `booking.unlockos.io`, `member.unlockos.io`, or an embedded booking screen on your own site. --- ## FAQ **Q. Do I need a separate Stripe account per facility?** You need one per entity that receives the money (per organization). Payouts go directly to the bank account of the registered Stripe account. **Q. I forgot my secret key.** Issue a new key in the Stripe Dashboard and register it again here. UnlockOS never displays a stored secret key. **Q. I launched while still in test mode.** Switch to live mode and save again. Payments accepted during test mode did not actually settle, so review the payment status of the affected bookings individually. **Q. I tried to save a live key (like `sk_live_...`) into the test fields and got an error.** The test fields only accept keys in the `pk_test_...` / `sk_test_...` form. Trying to save a live key (`pk_live_...` / `sk_live_...`) into a test field fails at save time with an error (error code: `STRIPE_KEY_MODE_MISMATCH`) and nothing is stored. The same applies in reverse — a test key cannot be saved into a live field. This check exists because a facility once had a live key saved into the test field: the screen kept showing "test mode" while real cards were actually being charged, and every test card number (like `4242...`) was declined. The mix-up is easy to miss because a Stripe key looks like an equally valid string regardless of which environment it belongs to. If you hit this error, check that the key you pasted actually belongs to the environment (test or live) you think it does, confirm the toggle in the Stripe Dashboard, and register it again. **Q. Who submits the security measures declaration?** The merchant that holds the Stripe contract — that is, your facility. UnlockOS cannot submit it on your behalf. Use this article as reference and confirm it against how your facility actually operates.