Japan: pay-at-the-end table ordering with our own system and Square Terminal (itemized checkout, split payments, receipts, KDS)

We are planning a daytime takeout shop and an evening dine-in izakaya at the same premises in Japan. We are evaluating our own ordering and table-bill system, with Square for payments, receipts, the kitchen display and cash management. Before we start building, we would like to confirm the following for Japan production. Answers to any part would be very helpful.

What we want to do

  • At the izakaya, guests scan a QR code at their table and place several rounds of orders from their own phones. They pay once when they leave, at the counter. This is the usual way to pay at an izakaya in Japan.
  • Square Online QR ordering in Japan takes payment for each order, and we have not found documentation confirming that open tabs are available in Japan. So we plan to keep the table’s orders in our own system and use Square for the payment.
  • We have read the recent answers in forum topics 28608 and 28269: unpaid API orders reach Square POS, KDS and printers only after they are paid, an app cannot add items to a check opened in Square POS, and the supported way to collect payment for an API order on hardware is a Terminal API checkout that references the order_id.
  • So at checkout, we plan to create an itemized order for the whole table with the Orders API and send a Terminal checkout with that order_id to a Square Terminal at the counter.
  • Groups often split the bill. At one table, some guests pay by card, some by e-money or PayPay, and some in cash, and some guests pay their share and leave before the others. The rest of the table may order more after that. Guests also often ask for a formal receipt (ryoshusho) addressed to their company. Receipts need to work as simplified qualified invoices in Japan.
  • Some reservations include a deposit that the guest pays in advance online. It must be applied to the table bill at checkout.
  • Each round of orders must reach the kitchen (Square KDS) as soon as it is placed, long before the table pays, without counting the items twice in sales or showing them twice in the kitchen.

Our main questions are whether this payment and receipt workflow is supported in Japan, and how to send kitchen tickets before payment.

A. Itemized checkout, split payments, deposits and receipts

  1. Formal receipts. The Develop for Japan guide (Develop for Japan) says for the itemized approach: “Formal receipts are not currently supported - only normal receipts can be printed.” The Take Payments for Orders guide (Take Payments for Orders) says: “For Square accounts in Japan, the Square Terminal prints both a standard receipt and a formal receipt called ryoshusho (領収書).” Which statement applies to an itemized Terminal checkout with an order_id in Japan? Guests often ask for a ryoshusho addressed to their company. For an API-created order, how is the recipient name entered, and is it printed on the ryoshusho?
  2. Split payments with mixed payment methods. We understand the documented split-tender flow: partial Terminal checkouts with checkout.payment_options.autocomplete=false against one order_id, plus cash recorded with CreatePayment (autocomplete=false), completed together with PayOrder (shown as Beta). The guide says: “Split tenders are available in regions that support order IDs for checkouts.” In Japan, we select the payment method using checkout.payment_type: CARD_PRESENT for card payments, one of the FELICA_* values for e-money, or QR_CODE for QR-code payments such as PayPay (as explained in forum topic 28116). The PaymentOptions reference says that delay_duration “is only supported for card payments”. Can FELICA_* and QR_CODE (PayPay) checkouts be created with checkout.payment_options.autocomplete=false against an order_id, and completed through PayOrder together with card and cash payments? If not, what workflow do you recommend for splitting a table bill while keeping itemized receipts?
  3. Receipt content. We need the printed receipt to show the seller’s invoice registration number, totals and tax amounts by tax rate, and reduced-rate item indicators where applicable. Are these supported for API-created orders, including cash-only payments and split payments? Which API fields or seller settings control them?
  4. Receipts during a split. Some guests pay their share and leave before the others. What document can Square Terminal issue while that guest’s payment is still APPROVED, before PayOrder? After PayOrder, does a RECEIPT Terminal action show that payment’s amount, the full order total, or both? To print an itemized receipt for the whole order, which payment_id should we pass?
  5. Adding or removing items after some guests have paid. After one guest has paid their share, the rest of the table may order another round, or a dish may be canceled. In forum topic 9596, a Square team member described this sequence: create an order, take a payment against it with autocomplete=false, add a line item with UpdateOrder, take another payment for the additional amount, and complete the payments with PayOrder. Does this also work in Japan when the payments are created through Terminal checkouts with checkout.payment_options.autocomplete=false? Assume the earlier Terminal checkouts are COMPLETED, their Payments remain APPROVED, the order remains OPEN, and no checkout is pending or in progress. Can UpdateOrder add items, reduce quantities, or remove items while retaining those approved payments? Does the answer change if the revised order total falls below the sum of the approved payment amounts? If an update is not supported, what workflow do you recommend?
  6. Reservation deposits. For some reservations, the guest pays a deposit in advance through a Checkout API payment link, which creates its own paid order. At the table checkout, we need to apply that deposit to the table’s itemized order. The receipt should show the total for the whole table, the deposit applied, the amount paid now, and the tax amounts by tax rate for the whole table. In forum topics 8945 and 10253 (2023), a Square team member said that applying an already paid order to another order is not available, and suggested an order-level discount, or a separate order for the deposit linked through reference_id, metadata or custom attributes. The deposit is an advance payment toward the meal, not a price reduction. According to the Order Calculation Guide for Japan, a tax-basis-reducing discount would cause Square to calculate tax on the discounted amount. Using such a discount to represent the deposit would therefore reduce the tax shown for the table order, whereas we need the receipt to show tax on the full meal amount. Is a catalog discount with modify_tax_basis set to DO_NOT_MODIFY_TAX_BASIS supported for orders in Japan, and how would it appear on the Terminal receipt and in sales reports? Is there a better supported way to apply a deposit in Japan?

B. Kitchen tickets on Square KDS before payment

Why we ask: the kitchen needs each round of orders right away, but the table pays only at the end. From forum topic 28028, we understand that paying a zero-total order with PayOrder and an empty payment_ids array is supported, that such an order is expected to route to KDS, and that ad hoc items are treated as uncategorized on KDS.

  1. Can you confirm that this workflow is supported for Square KDS in Japan production? For dine-in kitchen tickets, is a PICKUP fulfillment appropriate for these zero-total orders when IN_STORE (a restricted Beta) is not available to us? Should we use zero-priced ad hoc line items, or catalog items with a 100% discount? How would each choice affect item sales, quantities and discount reports, given that the same items are sold again in the final paid order?
  2. Which of ticket_name (shown as Beta), line_items[].note and fulfillments[].pickup_details.note appear on the KDS ticket? We want the kitchen to see the table number.
  3. To avoid sending the final billing order to the kitchen again, can we omit fulfillments from the billing order while keeping Terminal itemization and receipts? Would that prevent a second KDS ticket?
  4. If a guest cancels one line item in a multi-item zero-total order already displayed on KDS, can an API update remove or mark only that item as canceled while leaving the remaining items active? Forum topic 27132 says a scheduled print cannot be suppressed once a paid fulfillment is canceled. If an API update cannot do this, is a separate cancellation ticket identifying the original order and the canceled item the recommended workaround for KDS?
  5. For these API-created zero-total PICKUP orders, does completing a ticket on a Prep station or an Expeditor station update the fulfillment state exposed by the Orders API? If so, which state transitions occur, and which webhook events are emitted?

C. Cash drawer

Why we ask: we plan to use Square POS cash management as the record of the counter’s cash, and reconcile it with the cash that our system records for table bills.

  1. Is the Cash Drawer Shifts API available for Japan accounts? For a Japan location, does a CreatePayment request with source_id=CASH, later completed through PayOrder, count toward cash_payment_money or expected_cash_money in an open Square POS cash drawer shift at the same location? An existing answer in forum topic 26374 says that API payments are not expected to appear in the cash drawer. Does that also apply to this cash-payment flow?

D. Scheduled pickup orders (the takeout shop)

Why we ask: the daytime takeout shop takes pre-orders paid online through a Checkout API payment link. The kitchen should see each order only when it is time to prepare it.

  1. The Order Fulfillments guide says a scheduled order does not show up on a KDS “until pickup time minus prep time.” We will set schedule_type=SCHEDULED, pickup_at, and prep_time_duration. Assuming payment completes before the preparation window and staff do not manually advance the order, are there any exceptions or additional settings required to keep these CreatePaymentLink orders off KDS until pickup_at minus prep_time_duration in Japan?

E. Storing a card for no-show fees (reservations)

Why we ask: for reservations, we want to save a guest’s card without charging it, and charge an agreed no-show fee later if the guest does not come.

  1. We plan to save a card using the documented intent=STORE → CreateCard flow (also mentioned for a Japan seller in forum topic 28507), and later charge the agreed no-show fee with CreatePayment as a seller-initiated payment. Are there any Japan-specific requirements or limitations for charging a no-show fee this way? The Web Payments SDK reports from Japan production in forum topics 28329 (CHARGE and CHARGE_AND_STORE) and 28461 do not report a STORE test. Has Square confirmed whether STORE is affected?

Thank you.

Thanks for the detailed write-up. Here’s what we can confirm, and how to test the rest.

What we can confirm:

  • Split payments (2): Your flow matches Take Payments for Orders. Send Terminal checkouts with the order_idand autocomplete=false, and record cash with CreatePayment. Then call PayOrder with every payment ID. Any approved payment left out of payment_ids is canceled.
  • It looks like E-money and QR (2): autocomplete=false only works with CARD_PRESENT or MANUAL_CARD_ENTRY. FELICA_*and QR_CODE checkouts must be for the full order total. So they can’t be used for one guest’s share of a split bill. (Worth testing to confirm).
  • Order updates (5): Don’t update an order while its Terminal checkout is IN_PROGRESS. Cancel the checkout, update the order, then create a new checkout.
  • Formal receipts (1): You’re right that Develop for Japan and Take Payments for Orders conflict on this, so please include it in your testing. Check both a single full payment and a split payment.
  • Invoice-system receipts (3): Compliance with Japan’s Tax Invoice System says the Terminal API doesn’t support storing tax information on reports. For tax, use scope: ORDER on all taxes, per the Order Calculation Guide for Japan.
  • KDS (9, 13): Per Manage Order Fulfillments, orders with fulfillments show in Square products only after they’re paid, and IN_STORE is a closed beta. A billing order without a fulfillment isn’t sent to KDS. A SCHEDULED pickup shows on KDS at pickup time minus prep time.
  • Cash drawer (12): CASH payments recorded through the API aren’t added to a Square POS cash drawer shift.

Test the rest in production:

I can’t test the undocumented behavior myself, because I can’t reproduce a Japan production setup. If you or the seller have a Square account manager or partner manager, they can request to escalate these questions for additional localized support.

Otherwise, test with a real Square Terminal and KDS:

  • 1, 3, 4: Formal receipt options, recipient name, invoice registration number, tax by rate, and what a RECEIPTaction prints for one split payment.
  • 5, 6: Changing items while payments are APPROVED, and a DO_NOT_MODIFY_TAX_BASIS discount on receipts and reports.
  • 7, 8, 10, 11: A zero-total PICKUP order paid with PayOrder. Check whether it reaches KDS, which fields show on the ticket, what happens when an item is removed, and whether completing the ticket triggers webhooks.
  • 14: Storing a card with intent=STORE and charging a small no-show fee.

To test safely, use your own cards and small amounts outside service hours. Use a test location or KDS station so test tickets don’t reach the kitchen. Cancel or refund test payments afterward. Avoid PASMO and SUICA, because those payments can’t be refunded. If an e-money test payment errors, the buyer cancels it on the Terminal. CancelTerminalCheckout doesn’t support this (Take E-Money Payments)

Please share what you find here, without IDs or customer details. It will help other developers building in Japan.

Thanks again for the detailed answers. Square Japan support referred our API questions to this forum, so we have four follow-up questions about the documentation and API data for a seller in Japan.

1. Tax information for Terminal API payments
The Japan invoice system doc (Compliance with Japan's Tax Invoice Preservation System) says: “For storing tax information on reports, Square’s hardware-based APIs such as Terminal API don’t support this workflow.”

  • Which reports or fields does this refer to?
  • Suppose we create an itemized order with the Orders API, with 8% and 10% taxes using scope: ORDER and line-item pricing_blocklists so that each item has only its applicable tax rate, and the order is paid on Square Terminal through the Terminal API. Does this limitation affect the tax rates, tax amounts, or line-item amounts we can read through the Orders API afterwards (for example taxes with applied_money, and applied_taxes on each line item) for calculating totals by tax rate?

2. Payment completion after DeletePaymentLink
For a takeaway order awaiting payment through a Checkout API payment link, we delete the link when our payment deadline passes. We manage pickup in our own system and do not specify a PICKUP fulfillment when creating the link. The DeletePaymentLink reference says deleting a payment link cancels the associated order. After DeletePaymentLink succeeds with cancelled_order_id and RetrieveOrder returns state: CANCELED, can a payment that the buyer started before the deletion still reach COMPLETED? We mean a payment that completes after the cancellation, not a delayed webhook for a payment that had already completed. If the cancellation alone is not enough, which documented API checks tell us that no payment has completed or can still complete for that order?

3. Completion time of a payment link payment
We need to determine whether a payment link payment reached COMPLETED before our deadline, even if the webhook arrives later. For card payments, can we use card_details.card_payment_timeline.captured_at for this purpose, and is it always populated for completed payments? If not, which timestamp or documented method should we use? Please also explain any differences for Apple Pay and Google Pay, or any other payment methods that Checkout API supports in Japan.

4. Paying a dine-in table’s order from the customer’s phone
For a dine-in table, we may also let one customer pay the whole itemized order on their own phone instead of at the register. We understand that the “Terminal API is your only option” note in Develop for Japan is about in-person integrations. In Japan, can we accept payment for an existing Orders API order on our own web page, using the Web Payments SDK and CreatePayment with order_id for the full order total (card, Apple Pay, Google Pay)? Are there any restrictions when the order is for a dine-in table?
Also, the Supported Payment Methods by Country page (Supported Payment Methods by Country) marks PayPay as supported in Japan. Does that include the Web Payments SDK or Checkout API, or only in-person payments?

Thanks!