Develop for Japan

You can use Square APIs and SDKs to build applications that support and process in-person or online payments for sellers in Japan. Before you begin development, be sure to familiarize yourself with which payment methods are available in Japan and the pricing models for payments made with Square APIs and Square hardware.

If you have an existing POS system and want to connect to Square in-person payment solutions in Japan, you have two integration options:

• The Terminal API is compatible with Square Terminal devices. It connects directly to Square servers, making it available for almost any system, including Windows-based systems, web applications, or other platforms, because it connects directly to Square servers.
• The Point-of-Sale API works with Square Reader devices and operates via mobile devices only. It uses the Square mobile app for checkout, utilizing deep link functionality to switch between your app and Square.

• If your goal is to process itemized orders, the Terminal API is your only option.
• The Point-of-Sale API supports only custom amount-based transactions.
• If your external POS system manages itemized orders, syncing itemized sales with Square can allow you to:
  • Print itemized receipts.
  • Keep itemized transactions synchronized between systems.

When implementing in-person payment applications, you should process payments in-store with the Square Terminal or Square Reader devices. Staff must be present in the store or close enough to attend at any time when payment processing is required.

When integrating with Square in-person payment APIs, you'll need to choose between two integration approaches based on your business needs:

Japanese merchants can accept several payment methods for in-person transactions, including credit cards, digital wallet payments (Apple Pay and Google Pay), gift cards, e-money, prepaid IC cards (such as SUICA and PASMO), and QR code payments (such as PayPay, Alipay, Rakuten Pay, and au PAY).

Square provides a Sandbox environment where you can test your in-person payment integrations before going live. However, there are important differences between Sandbox and production testing for physical devices.

You can test Terminal API integrations in the Sandbox without connecting to a physical Square Terminal. Square provides special test device IDs that simulate different checkout scenarios, including successful payments, canceled payments, and timeout scenarios. This allows you to develop and test your integration logic without needing physical hardware.

The Sandbox environment supports testing various payment methods specific to Japan, including:

• E-money (FELICA) payments - Test e-money/FeLiCa transactions using dedicated test device IDs
• QR code payments (PayPay) - Test PayPay QR code payments (note: the Sandbox location must be based in Japan)

Example Test Device IDs:

For a complete list of test device IDs and their behaviors, see Terminal API Sandbox Testing.

Testing with an actual Square Terminal device is only supported in the production environment. The Sandbox environment does not support connections to physical Square Terminal devices. When testing with a physical device in production, you can use the minimum payment amount of 1 yen to minimize testing costs.

Use the following workflow for testing:

1. Conduct initial development and testing in Sandbox using test device IDs.
2. Perform final testing in production using a Square Terminal and small payment amounts (minimum 1 yen).

For more information, see Test Square APIs in the Sandbox.

For online payments in Japan, merchants can accept credit cards, debit cards, gift cards, and digital wallet payments (Apple Pay and Google Pay) when customers purchase through a web browser or mobile app.

You can build custom checkout forms using either the Web Payments SDK or In-App Payments SDK, and you can localize these forms from English to Japanese to provide a better customer experience.

• Use the Web Payments SDK for web applications or browser-based checkouts (desktop and mobile).
• Use the In-App Payments SDK for native mobile applications on iOS and Android.

What does this mean for your integration?

• Depending on the card issuer, 3DS authentication may be required during card transactions.
• Use the Web Payments SDK or In-App SDK to implement the 3DS flow.
• Merchants cannot disable or opt out of 3DS in Japan.

In a Payment object, gift cards, credit cards, debit cards, and e-money (FELICA) payments are all recorded with a source_type of CARD. Detailed information is available through the card_details field. Terminal checkout objects also use the CheckoutOptionsPaymentType enum to denote whether the payment was made with a card, e-money, or QR.

To retrieve payment information, you can use the GetTerminalCheckout, RetrieveOrder, or GetPayment endpoints depending on your needs.

The card_details object includes a card_brand enum that helps you distinguish between different payment methods.

• Credit cards show the international brand name (such as VISA or Mastercard).
• E-money payments show FELICA (updated from the previous value OTHER_BRAND).

{
  "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": "FELICA",
            "last_4": "{LAST_FOUR}"
          },
          "entry_method": "CONTACTLESS"
        }
      }
    ]
  }
}

1. Get a transaction ID from a completed checkout.
2. Retrieve the corresponding Order object using the Orders API.
3. Use the tenders.id value to get a Payment object with GetPayment. The Payment object will return CardPaymentDetails.Card.CardBrand with the value FELICA.

Terminal checkouts use payment_ids for payments, so you can use GetPayment directly to get payment information without needing to go through the Order object first.

For non-itemized sales, the item_type for orders created with e-money payments, are CUSTOM, because there's a custom amount for the payment. Itemized sales use the ITEM item type instead.

For more information, see Take E-Money Payments in Japan.

The wallet_details property in a Payments object supports several QR code brands, including:

• PAYPAY
• ALIPAY
• RAKUTEN_PAY
• AU_PAY
• D_BARAI
• MERPAY
• WECHAT_PAY. If a different brand is used that doesn't match these values, it is recorded as UNKNOWN.

Example Order object with a QR code payment:

{
  "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"
      }
    ]
  }
}

Note that the tenders object array in an order object doesn't have a value defined for wallet_details.

For implementation guides on accepting QR code payments, see

• Accept PayPay Payments in Japan for the Point of Sale API
• PayPay QR Code Payments for the Terminal API
• Take E-Money Payments in Japan.

When a request fails, Square API endpoints return a response with an errors field containing one or more Errors.

• Error messages are always returned in English. You need to retrieve the error object as a JSON object and translate the error details for Japanese users. Your application should take appropriate action based on the error.category, error.code, and error.field (which indicates where the error occurred).

• Specific refund limitations for transportation cards. If a buyer uses a PASMO or SUICA transportation card for a payment, you encounter a REFUND_DECLINED error. The seller cannot issue a refund for those payment cards.

Example refund decline error response:

{
  "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 is not supported.

If an error occurs on Square Terminal during an e-money payment, the checkout request has the IN_PROGRESS or PENDING state. In this situation, the buyer must manually cancel the checkout. To do so:

• Close the error message window
• Tap the navigation button back to the checkout screen
• Cancel the checkout manually.