Japan: recurring card-on-file payments using our own scheduler — MIT/3DS and API requirements

Questions
, , ,
1

Hello Square Developer Support,

We are integrating Square into a subscription-based web service in Japan. Square Japan Support referred us to this forum for technical guidance.

First, we would like to clarify our intended integration: card details are collected through the Web Payments SDK and stored by Square through the Cards API. We do not intend to store raw card numbers or CVVs on our servers. Our backend uses Square customer IDs and card IDs to request payments.

Our intended flow is:

  • Collect card details and perform buyer verification using the Web Payments SDK, passing verification details to card.tokenize().
  • Save the card using the Cards API.
  • On renewal dates, call CreatePayment from our backend with the saved card ID as source_id and the associated customer_id, without the customer being present.
  • Manage billing dates and amounts ourselves, without using the Subscriptions, Invoices, or Orders APIs.
  • For retryable renewal failures, make up to three additional attempts, seven days apart.

We would appreciate clarification on the following points for Japanese seller accounts.

  1. Merchant-initiated payments and 3DS

In our Sandbox tests, CreatePayment succeeded with customer_details containing customer_initiated: false and seller_keyed_in: false. Omitting customer_details resulted in CARD_DECLINED_VERIFICATION_REQUIRED.

However, the Cards API documentation says that in production, a card-on-file payment is treated as seller-initiated when neither a verification token nor CustomerDetails is supplied.

For off-session recurring payments in Japan, should we omit customer_details or explicitly provide those two false values? Are there relevant differences between Sandbox and production?

What initial card-storage and buyer-verification requirements must be met for subsequent renewals to be treated as merchant-initiated transactions? If an issuer still requires authentication, what recovery flow should we implement?

  1. Recurring billing with our own scheduler

Is recurring billing through the Payments API, using Square-stored cards and our own scheduler rather than the Subscriptions API, a supported integration pattern?

Are there specific requirements for obtaining and retaining customer consent to card storage and recurring charges? If account eligibility or contractual requirements need confirmation through another support channel, please let us know.

  1. Retrying declined payments

Japan Support advised that retry limits depend on the card issuer rather than a Square-defined limit.

Are there documented guidelines, card-network restrictions, or decline codes indicating that a payment must not be retried? For retryable declines, is our proposed schedule of three additional attempts, seven days apart, appropriate?

  1. Content Security Policy for 3DS

Does the documented Web Payments SDK CSP configuration cover 3DS challenge screens for Japanese card issuers? Are any additional origins or directives required in the parent page’s CSP?

  1. CreatePayment idempotency retention

What is the guaranteed minimum retention period for a CreatePayment idempotency_key?

If a request times out and its outcome is unknown, how long can we safely resend the identical request with the same key? What reconciliation approach is recommended after that period?

Clarification of items 1 and 2 would be especially helpful. Links to relevant documentation or a minimal recommended request example would be appreciated.

Thank you.

3

Great questions. Following this thread. I’d also like clarity on whether customer_details should be omitted or set to false in production for Japan, plus confirmed guidance on 3DS recovery flows and retry limits.