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.
Caution
Stripe automatically presents your customers payment method options by evaluating their currency, payment method restrictions, and other parameters. We recommend that you configure your payment methods from the Stripe Dashboard using the instructions in Accept a payment.
If you want to continue manually configuring the payment methods you present to your customers with Checkout, use this guide. Otherwise, update your integration to configure payment methods in the Dashboard.
Konbini is a single use payment method where customers are required to take additional steps to complete their payment. Customers pay by providing a payment code, confirmation number, and cash payment at Japanese convenience stores. Stripe notifies you when the payment is completed.
Determine compatibility
A Checkout Session must satisfy all of the following conditions to support Konbini payments:
- Prices for all line items must be in the same currency (JPY).
- You can only use one-time line items (recurring subscription plans are not supported).
Accept a payment
Note
Build an integration to accept a payment with Checkout before using this guide.
Use this guide to learn how to enable Konbini—it shows the differences between accepting a card payment and using Konbini.
Enable Konbini as a payment method
When creating a new Checkout Session, you need to:
- Add
konbinito the list ofpayment_method_ types - Make sure all your
line_use theitems jpycurrency.
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_ | The number of calendar days before a pending Konbini payment expires. Valid values are from 1 to 60 days. See Expiration. | No | 3 |
Expiration
Pending Konbini payments expire right before midnight (23:59:59 JST) on the specified date. For example if expires_ 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.
Phone number
On the Konbini checkout form, your customers can optionally supply a phone number to use as their confirmation number. This simplifies their payment process at a convenience store where the in-store UI asks for the customer to provide a payment code and their confirmation number. Both are reflected in the payment instructions that Stripe displays after the customer submits their checkout form. If your customer doesn’t provide a phone number, Stripe generates a random confirmation number.
Stripe proactively blocks phone numbers consisting of only zeros.
Redirect to Stripe hosted voucher page
Note
Unlike card payments, the customer won’t be redirected to the success_url with Konbini payment.
After submitting the Checkout form successfully, the customer is redirected to the hosted_. The customer can reference the hosted page’s payment instructions for details on how to complete their payment. The page is viewable on desktop and mobile, as well as being printable.
Stripe sends a payment_intent.requires_action event when a Konbini voucher is created successfully. If you need to email your customers the voucher’s payment instructions link, you can locate the hosted_ in payment_intent.next_action.konbini_display_details. Learn more about how to monitor a PaymentIntent with webhooks.
Stripe allows customization of customer-facing UIs on the Branding Settings page. The following brand settings can be applied to the voucher:
- Icon—your brand image and public business name
- Accent color—used as the color of the Copy Number button
- Brand color—used as the background color
Fulfill your orders
Because Konbini is a delayed notification payment method, you need to use a method such as webhooks to monitor the payment status and handle order fulfillment. Learn more about setting up webhooks and fulfilling orders.
The following events are sent when the payment status changes:
| Event Name | Description | Next steps |
|---|---|---|
The customer has successfully submitted the Checkout form. Stripe has generated the Konbini voucher. You can choose to email the | Wait for the customer to pay at a Konbini. | |
| checkout.session.async_payment_succeeded | The customer has successfully paid the Konbini voucher. The PaymentIntent transitions to succeeded. | Fulfill the goods or services that the customer purchased. |
| checkout.session.async_payment_failed | The Konbini voucher has expired, or the payment has failed for some other reason. The PaymentIntent returns to a status of requires_. | Contact the customer via email and request that they place a new order. |
Test your integration
When testing your Checkout integration, select Konbini as the payment method and click the Pay button.
Provide the following values in the Checkout form 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.
| Confirmation number | Description | |
|---|---|---|
|
| Simulates a Konbini payment which succeeds after 3 minutes and the Example: hanako@test.com |
|
| Simulates a Konbini payment which succeeds immediately and the Example: succeed_immediately@test.com |
|
| Simulates a Konbini payment which expires immediately and the The Example: expire_immediately@test.com |
|
| Simulates a Konbini payment which never succeeds; it expires in 3 minutes and the The Example: expire_with_delay@test.com |
|
| Simulates a Konbini payment which never succeeds; it expires according to the Example: fill_never@test.com |
In order to test confirmation number errors you may use the following values:
01234567890simulates a confirmation number rejection.00000000000results in a validation error.
Expiration and cancellation
After the time specified by the expires_ 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_ time.
There is a buffer period to avoid premature payment failures in such an event. The PaymentIntent’s status changes to requires_. 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_. 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.
Caution
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_ we create new instructions and a new hosted_. You need to ensure that your customer is made aware of these.
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_ |
| 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_ |
Refund is in requires_ 45 days after creation | failed |
Refund is canceled from a requires_ 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_. 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 does not provide their bank account details within 45 days, the refund’s status transitions to failed and the refund.failed event is sent. This means that Stripe is unable to 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. |
|
| Refund fails. |
Testing Refunds Expiry
You can make an API call to simulate the expiry of a testmode refund.
curl https://api.stripe.com/v1/test_helpers/refunds/{{REFUND_ID}}/expire \ -X POST \ -u:sk_test_4eC39HqLyjWDarjtT1zdp7dc