Learn about different levels of functionality and support for international development.
When you build applications with the Square Developer platform for international sellers, some regions might have limited support and functionality.
The following sections provide context regarding building applications for Japanese sellers. Before reviewing these sections, become familiar with how different regions support Square payment methods.
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.
Consider the following scenarios when you build and manage applications for processing online and in-person payments for checkout flows.
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:
Web Payments SDK | In-App Payments SDK |
---|---|
Web Payments SDK | In-App Payments SDK |
Payment object technical reference | Localize In-App Payments |
Note
Online checkouts with Square Readers or Square Terminals aren't supported in Japan.
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
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.
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. QR code payments made in-person are supported only with PayPay. A seller needs to be approved before using PayPay.
The Terminal API and Point-of-Sale API are supported in Japan. The Reader SDK is supported only in the US.
Terminal API | Point of Sale API | |
---|---|---|
Connection method | Connection to Square server | Link to Square Point of Sale |
Accepted payment method | Cashless payments (card and digital wallet) and cash payments | Cashless payments and e-money payments (when CREDIT_CARD is specified) |
Guides | Terminal API | Point of Sale API |
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.
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.
{
"payment": {
"id": "{PAYMENT_ID}",
"created_at": "2023-10-13T21:14:29.577Z",
"updated_at": "2023-10-13T21:14:30.504Z",
"amount_money": {
"amount": 5000,
"currency": "JPY"
},
"source_type": "CARD",
"card_details": {
"status": "CAPTURED",
"card": {
"card_brand": "FELICA"
}
}
}
}
{
"order": {
"id": "{ORDER_ID}",
"created_at": "2023-10-13T21:15:54.577Z",
"updated_at": "2023-10-13T21:15:55.504Z",
"tenders": [
{
"id": "{PAYMENT ID}",
"location_id": "{LOCATION ID}",
"transaction_id": "{TRANSACTION ID}",
"created_at": "2023-10-13T21:15:54.577Z",
"amount_money": {
"amount": 5000,
"currency": "JPY"
},
"type": "CARD",
"card_details": {
"status": "CAPTURED",
"card": {
"card_brand": "OTHER_BRAND",
"last_4": "{LAST FOUR}"
},
"entry_method": "CONTACTLESS"
}
}
]
}
}
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.
The wallet_details
property in a Payments object supports the following QR code type of brands:
CASH_APP
PAYPAY
ALIPAY
RAKUTEN_PAY
AU_PAY
D_BARAI
MERPAY
WECHAT_PAY
UNKNOWN
, if another brand is used.
For QR code 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 QR code payment. The tenders object array doesn't have a value defined for wallet_details
.
{
"order": {
"id": "{ORDER_ID}",
"created_at": "2023-10-13T21:15:54.577Z",
"updated_at": "2023-10-13T21:15:55.504Z",
"tenders": [
{
"id": "{PAYMENT ID}",
"location_id": "{LOCATION ID}",
"transaction_id": "{ORDER ID}",
"created_at": "2023-10-13T21:15:55.504Z",
"note": "a custom note description",
"amount_money": {
"amount": 100,
"currency": "JPY"
},
"processing_fee_money": {
"amount": 3,
"currency": "JPY"
},
"type": "WALLET"
}
],
}
}
For more information about how your application can take QR code payments using Square APIs, see the following guides:
Point of Sale API | Terminal API |
---|---|
Accept PayPay Payments in Japan | PayPay QR Code Payments |
Take E-Money Payments in Japan |
The Square Developer Console shows data for 1 year, but only retains API logs for 28 days. You can view API logs in the Developer Console 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.
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"
}
]
}
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.
Each table references in-person feature availability by region.
The buyer's payment card is saved on file with Square and then used for a payment.
Country | Point of Sale API | Reader SDK | Terminal API |
---|---|---|---|
Australia | ✅ | ❌ | ✅ |
Canada | ✅ | ❌ | ✅ |
France | ✅ | ❌ | ✅ |
Ireland | ✅ | ❌ | ✅ |
Japan | ✅ | ❌ | ✅ |
Spain | ✅ | ❌ | ✅ |
United Kingdom | ✅ | ❌ | ✅ |
United States | ✅ | ✅ | ✅ |
Country | App Fee Money | Custom Amounts | Delay Capture | Itemization | Save Card on File |
---|---|---|---|---|---|
Australia | ❌ | ✅ | ❌ | ❌ | ✅ |
Canada | ❌ | ✅ | ❌ | ❌ | ✅ |
France | ❌ | ✅ | ❌ | ❌ | ❌ |
Ireland | ❌ | ✅ | ❌ | ❌ | ❌ |
Japan | ❌ | ✅ | ❌ | ❌ | ❌ |
Spain | ❌ | ✅ | ❌ | ❌ | ❌ |
United Kingdom | ❌ | ✅ | ❌ | ❌ | ❌ |
United States | ✅ | ✅ | ✅ | ✅ | ✅ |
Country | App Fee Money | Custom Amounts | Delay Capture | Itemization | Save Card on File |
---|---|---|---|---|---|
Australia | ❌ | ❌ | ❌ | ❌ | ❌ |
Canada | ❌ | ❌ | ❌ | ❌ | ❌ |
France | ❌ | ❌ | ❌ | ❌ | ❌ |
Ireland | ❌ | ❌ | ❌ | ❌ | ❌ |
Japan | ❌ | ❌ | ❌ | ❌ | ❌ |
Spain | ❌ | ❌ | ❌ | ❌ | ❌ |
United Kingdom | ❌ | ❌ | ❌ | ❌ | ❌ |
United States | ❌ | ✅ | ✅ | ❌ | ✅ |
Country | App Fee Money | Custom Amounts | Itemization | Save Card on File |
---|---|---|---|---|
Australia | ❌ | ✅ | ❌ | ❌ |
Canada | ❌ | ✅ | ❌ | ❌ |
France | ❌ | ✅ | ❌ | ❌ |
Ireland | ❌ | ✅ | ❌ | ❌ |
Japan | ❌ | ✅ | ❌ | ❌ |
Spain | ❌ | ✅ | ❌ | ❌ |
United Kingdom | ❌ | ✅ | ❌ | ❌ |
United States | ❌ | ✅ | ❌ | ❌ |