Regional Differences for International Development

When you build applications with the Square Developer platform for international sellers, some regions might have limited support and functionality.

This guide provides context regarding common use cases that impact non-US based sellers when you build Square solutions for them.

Did you know?

Before reviewing this guide, become familiar with how different regions support Square payment methods.

The following sections cover building applications for Japanese sellers.

Link to section

Overview

You can build applications to support and process online payments or in-person payments in Japan. Square provides client-side SDKs to build customized buyer-facing experiences, as well as server-side APIs to manage one-time and recurring itemized orders and payments.

Depending on the seller's business needs, you can build applications that take itemized sales or sales that calculate a non-itemized custom amount to be processed for checkout. With the Orders API, an Order object can take one of the following sales:

  • Itemized sale - Each line item has a tax and total amount.
  • Non-itemized (custom amount) sale - There's a single charge for all line items included in the sale.
Link to section

Processing payments for checkout

Consider the following scenarios when you build and manage applications for processing online and in-person payments for checkout flows.

Link to section

Payments made on a buyer's screen

Japanese sellers support payment methods with credit cards, debit cards, and gift cards. Digital wallet payments aren't supported. For more information, see Supported Payment Methods by Country.

For Japanese websites and mobile markets, you can build checkout forms with the Web Payments SDK or In-App Payments SDK, respectively, and localize the forms from English to Japanese. These SDKs support client-facing payments in Japan. Review the following to get started:

Note

Online checkouts with Square Readers or Square Terminals aren't supported in Japan.

Link to section

Online payments with Orders API integration

If your region supports the Orders API, both itemized checkouts and custom amount checkouts are supported for online payments, but not for in-person payments.

You can process payments that use an order_id in itemized checkouts or checkouts with custom amounts. In Japan, you can apply taxes to an order for online payments, which results in compliance with Japan's invoice system.

The following request examples illustrate various types of payment processing.

Create order

Include the order_id in the payment request.

Create payment

Create payment link

Link to section

Reporting Japanese taxes from Square orders

Online payments support calculating taxes from orders. Receipts indicate these taxes for any itemized checkout payments.

Sellers need to include their QII (Qualified Invoice Issuer) tax identifier number, which you can get using the RetrieveLocation endpoint. A Locations object contains the tax_ids.jp_qii number.

For more information about applying taxes to an order, see Apply Taxes and Discounts.

Link to section

Payments processed on Square seller hardware

The Terminal API and Point-of-Sale API don't support itemized checkouts with the Orders API in Japan. If a checkout needs to be associated with a buyer's payment, you need to process a non-itemized (custom amount) sale.

In-person payment applications should process payments in-store with a Square POS system and with the buyer and a seller team member present in the store. In Japan, because delayed capture and partial authorization aren't supported, the application must process payments and complete checkouts in-store. The following payment methods are supported for in-person payments for Japanese sellers:

  • Credit card
  • Gift cards
  • E-money
  • Prepaid IC (integrated circuit) cards
  • PayPay

To support e-money or PayPay payments, Japanese sellers must submit an application form to activate those payment methods. For more information, see Apply for electronic money.

The Terminal API and Point-of-Sale API are supported in Japan. The Reader SDK is supported only in the US.

Link to section

Terminal API vs. Point of Sale API for in-person payments

Terminal APIPoint of Sale API
Connection methodConnection to Square serverLink to Square Point of Sale
Accepted payment methodCashless payments (card and digital wallet) and cash paymentsCashless payments and e-money payments (when CREDIT_CARD is specified)
GuidesTerminal API OverviewPoint of Sale API Overview
Link to section

Sales reporting

For information about Japan's invoice system and how you can reach compliance with sales reporting application tasks, see Compliance with Japan's Tax Invoice Preservation System. The following sections describe Japan's supported payment methods for sales reporting.

Link to section

FELICA payments

In a Payment object, gift cards, credit cards, debit cards, and e-money (FELICA) payments are recorded as the source_type of CARD with details available using card_details. Terminal checkout objects also use the CheckoutOptionsPaymentType enum to denote card, e-money, and PayPay payment types. Use GetTerminalCheckout, RetrieveOrder, or GetPayment to retrieve these checkouts. You can also get information about a checkout from an Order object for a custom amount order.

The card_details object includes a card_brand enum, which helps distinguish payment methods. For example, if a credit card is used, the international brand shows a credit card brand name such as VISA. E-money is indicated as OTHER_BRAND in the Orders API, but in the Payments API, e-money is indicated as FELICA.

The following are example Payment and Order object responses.

With the Point of Sale API and e-money payments, you can get a transaction ID from a completed checkout and retrieve an Order object with it using the Orders API. An Order object contains a tenders property, which has a tenders.id value that you can use to get a Payment object with GetPayment. The Payment object response returns CardPaymentDetails.Card.CardBrand with FELICA as the card brand property.

A Terminal checkout request uses payment_ids for payments, which means you can use GetPayment to directly get payment information. The difference between tender and payment is that tender represents a payment method used in a Square transaction, while payment represents a payment processed by the Payments API.

For an order created for a non-itemized sale with e-money payments, the item_type for a line item is CUSTOM because a non-itemized sale has a custom amount for payment. Itemized sales use the ITEM item type.

For more information about e-money payments and the Terminal API, see Take E-Money Payments in Japan.

Link to section

PayPay payments

For PayPay payments, Payment objects refer to them as a WALLET source type in the wallet_details property.

In the following response example, the Orders API returns an Order object with the WALLET source type and the payment is for a PayPay transaction. The tenders object array doesn't have a value defined for wallet_details.

For more information about how your application can take PayPay payments using Square APIs, see the following guides:

The Square Developer Dashboard shows data for 1 year, but only retains API logs for 28 days. You can view API logs in the Developer Dashboard or API Explorer. If you need to capture historical data about PayPay payments and purchases, use Square API Explorer. For more information, see API Logs Overview.

Link to section

Error handling for failed requests

When a request fails, Square API endpoints return a response that includes an errors field in the response body. The response contains one or more errors of the Error type.

Because the error messages are always in English, you need to retrieve the error object as a JSON object and translate the details of the error. You also need to take action based on the error category, error code, and field where the error took place.

If a buyer uses a PASMO or SUICA transportation card for a payment and you encounter an error, the seller cannot issue a refund for those payment cards. E-money, PaPay, and other transportation cards are only available for in-person payments. Refunding a payment and recording the refund in the seller's Square account isn't supported.

The following shows an example error response of a declined refund request against PASMO or SUICA payments:

{ "errors": [ { "code": "REFUND_DECLINED", "detail": "Payment could not be refunded", "category": "REFUND_ERROR" } ] }
Link to section

Errors with canceling an e-money payment

Using CancelTerminalCheckout to cancel an e-money payment after getting an error on the Square Terminal isn't currently supported. If the Square Terminal gets an error, the buyer needs to close the error message window and then tap the navigation button back to the checkout screen to cancel the checkout. The checkout request has the IN_PROGRESS or PENDING state when this error occurs.

Link to section

Product and feature availability

Each table references in-person feature availability by region.

Link to section

Card payment product availability

The buyer's payment card is saved on file with Square and then used for a payment.

CountryPoint of Sale APIReader SDKTerminal API
Australia
Canada
France
Ireland
Japan
Spain
United Kingdom
United States
Link to section

Terminal API feature availability

CountryApp Fee MoneyCustom AmountsDelay CaptureItemizationSave Card on File
Australia
Canada
France
Ireland
Japan
Spain
United Kingdom
United States
Link to section

Reader SDK feature availability

CountryApp Fee MoneyCustom AmountsDelay CaptureItemizationSave Card on File
Australia
Canada
France
Ireland
Japan
Spain
United Kingdom
United States
Link to section

Point of Sale API feature availability

CountryApp Fee MoneyCustom AmountsItemizationSave Card on File
Australia
Canada
France
Ireland
Japan
Spain
United Kingdom
United States