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.

The following sections cover building applications for Japanese sellers.

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:

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.

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.

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:

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.

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.