Konbini payments

Use the Payment Intents and Payment Methods APIs to accept payments through Konbini, a common way to make payments through convenience stores in Japan.

Stripe users in Japan can accept Konbini payments from customers in Japan by using the Payment Intents and Payment Methods APIs. Customers pay by providing a payment code, confirmation number, and cash payment at Japanese convenience stores. Stripe notifies you when the payment is completed.

Set up Stripe
Server-side

First, you need a Stripe account. Register now.

Use our official libraries for access to the Stripe API from your application:

Create a PaymentIntent
Server-side

Stripe uses a PaymentIntent object to represent your intent to collect payment from a customer, tracking state changes from Konbini PaymentIntent creation to completion.

Create a PaymentIntent on your server with an amount and the jpy currency (Konbini does not support other currencies). If you already have an integration using the Payment Intents API, add konbini to the list of payment method types for your PaymentIntent.

Retrieve the client secret

The PaymentIntent includes a client secret that the client side uses to securely complete the payment process. You can use different approaches to pass the client secret to the client side.

Retrieve the client secret from an endpoint on your server, using the browser’s fetch function. This approach is best if your client side is a single-page application, particularly one built with a modern frontend framework like React. Create the server endpoint that serves the client secret:

And then fetch the client secret with JavaScript on the client side:

(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();

Additional payment method options

Payment method options can be specified in the payment method options under the konbini key.

Field	Value	Required	Default Value
`expires_after_days`	The number of calendar days before a pending Konbini payment expires. Valid values are from 1 to 60 days. See Expiration.	No	3
`expires_at`	A Unix timestamp at which the pending Konbini payment will expire. This expiry date must be more than 30 minutes from the current time and less than 60 days after the setting is applied to the PaymentIntent. See Expiration.	No	unset
`product_description`	A product descriptor of up to 22 characters, which will appear to customers at the convenience store. Presence of non-Shift JIS (JIS X 0208:1997) characters will cause an error to be returned. While not required, we recommend setting this option. Otherwise we fall back to a generic placeholder chosen at our own discretion, e.g. お買い上げ商品・サービス.	No	placeholder

Expiration

Pending Konbini payments expire right before midnight (23:59:59 JST) on the specified date. For example if expires_after_days is set to 2 and the PaymentIntent is confirmed on Monday, the pending Konbini payment will expire on Wednesday at 23:59:59 Japan (UTC+9) time.

The expires_at setting is a Unix timestamp in seconds. If the value is less than 30 minutes from the current time, or the PaymentIntent confirmation happens less than 30 minutes from the expiration time, an error will be returned.

expires_after_days and expires_at are mutually exclusive. An error will be returned if both are set. Both are also optional, and if neither are set, the expiration time defaults to 3 days after PaymentIntent creation at 23:59 Japan (UTC+9) time.

Error handling

Requests on PaymentIntents such as creation, updates, and confirmation may fail. You can inspect the error value of the API response to determine the reason and in many cases either resubmit the request or correct the error. In particular, if you provide a value for the confirmation_number payment method option, you may want to handle specific error codes we return. See Confirmation numbers for more details.

The payment method may at times become temporarily unavailable due to outages, scheduled maintenance, or your usage patterns. See Handling temporary availability issues for more details.

Collect payment method details
Client-side

Create a payment form on your client to collect the required billing details from the customer:

Field	Value
`name`	The full name of the customer, truncated to a maximum of 20 characters in convenience store UIs and receipts. Non-Shift JIS (JIS X 0208:1997) characters will be dropped or replaced.
`email`	The full email address of the customer.

The form example here also collects a phone number, to be used as a customer-provided confirmation number:

checkout.html
<form id="payment-form">
  <div class="form-row">
    <label for="name">
      Name
    </label>
    <input id="name" name="name" required>
  </div>

  <div class="form-row">
    <label for="email">
      Email
    </label>
    <input id="email" name="email" required>
  </div>

  <div class="form-row">
    <label for="phone">
      Phone Number
    </label>
    <input id="phone" name="phone" required>
  </div>

  <!-- Used to display form errors. -->
  <div id="error-message" role="alert"></div>

  <button id="submit-button">Pay with Konbini</button>
</form>

Submit the payment to Stripe
Client-side

When a customer clicks to pay with Konbini, use Stripe.js to submit the payment to Stripe. Stripe.js is our foundational JavaScript library for building payment flows.

Include the Stripe.js script on your checkout page by adding it to the head of your HTML file.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/v3/"></script>
</head>

Create an instance of Stripe.js with the following JavaScript on your checkout page.

client.js
// Set your publishable key. Remember to switch to your live publishable key in production!
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

Use stripe.confirmKonbiniPayment and the client secret of the PaymentIntent object that you created in Step 2 to submit the customer’s billing details.

Upon confirmation, Stripe will automatically open a modal to display the Konbini payment instructions to your customer.

client.js
const form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const result = await stripe.confirmKonbiniPayment(
    '{{PAYMENT_INTENT_CLIENT_SECRET}}',
    {
      payment_method: {
        billing_details: {
          name: document.getElementById('name').value,
          email: document.getElementById('email').value,
        },
      },
      payment_method_options: {
        konbini: {
          confirmation_number: document.getElementById('phone').value.replace(/\D/g,''),
        },
      },
    }
  );
  // Stripe.js will open a modal to display the Konbini payment instructions to your customer
  // This async function finishes when the customer closes the modal

  if (result.error) {
    // Display error to your customer
    const errorMsg = document.getElementById('error-message');
    errorMsg.innerText = result.error.message;
  }
});

Catatan

stripe.confirmKonbiniPayment may take several seconds to complete. During that time, disable your form from being resubmitted and show a waiting indicator like a spinner. If you receive an error, show it to the customer, re-enable the form, and hide the waiting indicator.

Additional payment method options

When confirming a Konbini PaymentIntent, you can specify additional payment method options in the payment method options, under the konbini key.

Field	Value	Required	Default value
`confirmation_number`	A 10 to 11-digit numeric string. This string is also shown in the payment instructions and can’t consist of only zeroes. If you don’t provide a value for `confirmation_number`, Stripe randomly generates one for you. For more information, see Confirmation numbers.	No	unset

Confirmation numbers

Your customers will need to refer to the confirmation_number when completing their payment. A common suggestion for this value, if you choose to set it or allow your customers to set it, is the customer’s phone number. A confirmation_number may also be set during server-side PaymentIntent creation, but more commonly would be set client-side by the customer during PaymentIntent confirmation. It may be updated from the value set during PaymentIntent creation all the way until confirmation.

If a specified confirmation_number is too common among all ongoing convenience store transactions it may be rejected at the time of PaymentIntent confirmation. The error code returned in this case would be payment_intent_konbini_rejected_confirmation_number, which would only be expected when confirming a PaymentIntent.

Stripe proactively blocks confirmation numbers consisting of only zeros at PaymentIntent creation as well as during update and confirmation. Please ensure on your end that you don’t set this value or allow customers to set it.

Error handling

Confirming a PaymentIntent client side may also fail. You should inspect the error return value to determine why and possibly show the error to the customer or correct the error and try again.

OpsionalDisplay your own Konbini payment instructions to your customer
Client-side

OpsionalSubmit the payment to Stripe from your server
Server-side

OpsionalCustomize payment instructions

OpsionalSend payment instruction emails

OpsionalSend reminder emails

Handle post-payment events
Server-side

Konbini is a delayed notification payment method, so funds are not immediately available. Customers might not pay for the pending Konbini payment at a convenience store immediately after checking out.

After a pending Konbini Payment completes, Stripe sends a payment_intent.succeeded event for it. Use the Dashboard or build a webhook handler to receive these events and run actions. Examples of actions include sending an order confirmation email to your customer, logging the sale in a database, or starting a shipping workflow.

When it’s clear that a pending Konbini payment didn’t complete, typically about an hour after its expiration deadline, Stripe sends a payment_intent.payment_failed event.

Event	Description	Next steps
`payment_intent.requires_action`	The pending Konbini payment is created.	Optionally, send the customer to the payment instructions page. Wait for the customer to pay the Konbini payment.
`payment_intent.succeeded`	The customer paid for the pending Konbini payment before expiration.	Fulfill the goods or services that the customer purchased.
`payment_intent.payment_failed`	The customer didn’t pay the pending Konbini payment before expiration.	Contact the customer using email or push notification to request another payment method.

Catatan

While testing, the status of a Konbini PaymentIntent might automatically change based on the parameters sent, such as email. You can confirm any updates on the Dashboard. See Test the integration for more details.

Receive events and run business actions

Manually

Use the Stripe Dashboard to view all your Stripe payments, send email receipts, handle payouts, or retry failed payments.

View your test payments in the Dashboard

Custom Code

Build a webhook handler to listen for events and build custom asynchronous payment flows. Test and debug your webhook integration locally with the Stripe CLI.

Build a custom webhook

Test the integration

While testing, set payment_method.billing_details.email to the following values when you call stripe.confirmKonbiniPayment to test different scenarios. You can either test with a special confirmation number or an email pattern. If both are provided, the behavior of the special confirmation number applies.

Email	Confirmation number	Description
`{any_prefix}@{any_domain}`	`11111111110`	Simulates a Konbini payment which succeeds after 3 minutes and the `payment_intent.succeeded` webhook arrives after that. Example: hanako@test.com
`{any_prefix}succeed_immediately@{any_domain}`	`22222222220`	Simulates a Konbini payment which succeeds immediately and the `payment_intent.succeeded` webhook arrives after that. Example: succeed_immediately@test.com
`{any_prefix}expire_immediately@{any_domain}`	`33333333330`	Simulates a Konbini payment which expires immediately and the `payment_intent.payment_failed` webhook arrives after that. The `expires_at` field in next_action.konbini_display_details is set to the current time regardless of what the `expires_after_days` or `expires_at` parameter in payment method options is set to. Example: expire_immediately@test.com
`{any_prefix}expire_with_delay@{any_domain}`	`44444444440`	Simulates a Konbini payment which never succeeds; it expires in 3 minutes and the `payment_intent.payment_failed` webhook arrives after that. The `expires_at` field in next_action.konbini_display_details is set to 3 minutes in the future regardless of what the `expires_after_days` or `expires_at` parameter in payment method options is set to. Example: expire_with_delay@test.com
`{any_prefix}fill_never@{any_domain}`	`55555555550`	Simulates a Konbini payment which never succeeds; it expires according to the `expires_at` field in `next_action.konbini_display_details` per the provided parameters in the payment method options and the `payment_intent.payment_failed` webhook arrives after that. Example: fill_never@test.com

In order to test confirmation number error handling, you can use the following values for payment_method_options[confirmation_number]:

01234567890 yields a payment_intent_konbini_rejected_confirmation_number error code.
00000000000 yields a generic validation error code. You should avoid this error in your integration using pre-validation.

Expiration and cancellation

After the time specified by the expires_at value in the next_action.konbini_display_details, the customer can no longer initiate the payment process for a pending Konbini payment at a convenience store kiosk. However, if they issued a valid payment slip before the deadline they may be able to complete the payment at the cash register after the expires_at time.

There is a buffer period to avoid premature payment failures in such an event. The PaymentIntent’s status changes to requires_payment_method. At this point, you can cancel or confirm the PaymentIntent with another payment method.

You can also cancel a pending Konbini payment after confirmation and before the time specified by next_action.konbini_display_details.expires_at. Updating the PaymentIntent or confirming it with another payment method will also implicitly cancel the existing Konbini payment.

If the customer is currently paying for the Konbini payment at the convenience store, the cancellation request will fail. Cancellation may be re-attempted if the customer abandons the payment attempt and after the payment slip expires.

Note that temporary payment method availability issues also affect (both explicit as well as implicit) cancellation requests.

Peringatan

When you cancel a pending payment the original payment instructions become invalid. For most use cases we suggest you reach out to your customer to inform them of the cancellation.

When you successfully reconfirm a PaymentIntent in status requires_action we create new instructions and a new hosted_voucher_url. You need to ensure that your customer is made aware of these.

Handle temporary availability issues

The following error codes indicate temporary issues with the availability of the payment method:

Code	Description	Handling
`payment_method_rate_limit_exceeded`	Too many requests are being made in quick succession for this payment method, which has stricter limits than our API-wide rate limits.	Retrying with backoff generally resolves the situation. However, in case of sustained heavy usage of the payment method (for example, during an ongoing sale on your website) these errors may persist for some amount of requests. In that case, asking your customers to consider choosing a different payment method may be an additional mitigation option.
`payment_method_not_available`	The payment method is experiencing unknown temporary issues that may potentially last for a while (for example, during outages or periods of scheduled maintenance).	It is best to invite your users to complete their purchase with a different payment method or try again at a later time.

Peringatan

If you anticipate heavy usage in general or for an upcoming event please reach out to us well ahead of time.

Refunds

It is possible to refund Konbini payments through the Dashboard or API.

To complete a refund sent to the customer’s bank account directly, your customer must provide the bank account details where they would like to receive the funds. Stripe contacts the customer at the email address from the billing details on the payment method and requests these details from them. After we receive the bank details, we process the refund automatically.

The refund’s status transitions as follows:

Event	Refund status
Refund is created	`requires_action`
Customer submits bank account details, and Stripe begins processing the refund	`pending`
Refund is expected to arrive in customer’s bank	`succeeded`
Customer’s bank returns the funds back to Stripe	`requires_action`
Refund is in `requires_action` 45 days after creation	`failed`
Refund is canceled from a `requires_action` state	`canceled`

If the customer’s bank can’t successfully complete the transfer, the funds are returned to Stripe and the refund transitions to requires_action. This can happen if the account holder’s name doesn’t match what the recipient bank has on file or if the provided bank account number has a typo. In these cases, Stripe emails the customer to inform them of the failure and to request that they resubmit their bank account details.

If your customer doesn’t provide their bank account details within 45 days, the refund’s status transitions to failed and we send the refund.failed event. This means that Stripe can’t process the refund, and you must return the funds to your customer outside of Stripe.

The instructions_email field on the refund is the email that the refund was sent to. While a refund is waiting for a response from the customer, details of the email sent to the customer can also be found under the next_action.display_details.email_sent field on the refund.

Each individual refund (including each partial refund) may incur a fee. Please reach out to your point of contact at Stripe to learn more about this.

Testing Refunds

You can test refund behavior in testmode using the following test bank accounts on the bank account details collection page linked in the email sent to the customer. Bank account details outside of these test bank accounts will not be accepted.

Routing Account Type

1100000 0001234 Refund succeeds.

Routing	Account	Type
`1100000`	`0001234`	Refund succeeds.
`1100000`	`1111113` `1111116` `1111113` `3333335` `4444440`	Refund fails.

1100000

1111113

1111116

1111113

3333335

4444440

Refund fails.

Testing Refunds Expiry

You can make an API call to simulate the expiry of a testmode refund.

Command Line
curl https://api.stripe.com/v1/test_helpers/refunds/{{REFUND_ID}}/expire \
  -X POST \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
:

Catatan

Konbini payments

Use the Payment Intents and Payment Methods APIs to accept payments through Konbini, a common way to make payments through convenience stores in Japan.

Set up StripeServer-side

Create a PaymentIntentServer-side

Retrieve the client secret

Additional payment method options

Expiration

Error handling

Collect payment method detailsClient-side

Submit the payment to StripeClient-side

Catatan

Additional payment method options

Confirmation numbers

Error handling

OpsionalDisplay your own Konbini payment instructions to your customerClient-side

OpsionalSubmit the payment to Stripe from your serverServer-side

OpsionalCustomize payment instructions

OpsionalSend payment instruction emails

OpsionalSend reminder emails

Handle post-payment eventsServer-side

Catatan

Receive events and run business actions

Manually

Custom Code

Test the integration

Expiration and cancellation

Peringatan

Handle temporary availability issues

Peringatan

Refunds

Testing Refunds

Testing Refunds Expiry

Set up Stripe
Server-side

Create a PaymentIntent
Server-side

Collect payment method details
Client-side

Submit the payment to Stripe
Client-side

OpsionalDisplay your own Konbini payment instructions to your customer
Client-side

OpsionalSubmit the payment to Stripe from your server
Server-side

Handle post-payment events
Server-side