stripe-japan-agent

name	stripe-japan-agent
description	Payment management for Japan — PayPay, konbini payments, subscriptions, invoicing via Stripe
author	hanabi-jpn
version	1.0.0
tags	["stripe","payments","japan","paypay","konbini","subscriptions","invoicing","fintech"]

╔═══════════════════════════════════════════════╗
║  ┌─────────────────────────────────────────┐  ║
║  │   S T R I P E   J A P A N   A G E N T  │  ║
║  │         ━━━━━━━━━━━━━━━━━━━━            │  ║
║  │    💳 決済 → 請求 → 分析 → インボイス    │  ║
║  │         Tekikaku Invoice Ready          │  ║
║  └─────────────────────────────────────────┘  ║
╚═══════════════════════════════════════════════╝

stripe-japan-agent tekikaku-invoice paypay konbini jpy-native

Accept every way Japan pays -- from konbini counters to PayPay QR codes, managed entirely from your terminal.

---

Overview

Stripe Japan Agent brings the full Stripe payment stack to the command line with first-class support for Japan-specific payment methods. In a market where credit cards account for only 30% of e-commerce transactions, supporting konbini (convenience store) payments, PayPay, and bank transfers is not optional -- it is table stakes. This agent wraps the Stripe API with opinionated defaults tuned for the Japanese market: JPY zero-decimal currency handling, proper furigana fields for customer names, and invoice formatting that complies with the Qualified Invoice System (Tekikaku Invoice) introduced in October 2023.

The agent operates in two modes. Interactive mode lets you create charges, manage subscriptions, and issue invoices through direct commands. Automation mode lets you pipe webhook events through the agent for real-time payment monitoring, automatic retry logic for failed konbini payments, and dispute response workflows. Both modes share the same authentication layer and output formatting engine.

  MERCHANT (CLI)
       |
       v
 +-----------+      +------------------+      +------------------+
 | Command   |----->| Stripe API       |----->| Payment Methods  |
 | Router    |      | (v2024-12-18)    |      |                  |
 +-----------+      +------------------+      | - Card (Visa/MC) |
       |                   |                  | - PayPay          |
       |                   |                  | - Konbini          |
       |                   v                  | - Bank Transfer    |
       |            +------------------+      +------------------+
       |            | Webhook Listener |             |
       |            | (localhost:4242) |             |
       |            +--------+---------+             |
       |                     |                       |
       v                     v                       v
 +-----------+      +------------------+      +------------------+
 | Dashboard |      | Event Processor  |      | Customer DB      |
 | Renderer  |<-----| (retry, notify)  |      | (Stripe-hosted)  |
 +-----------+      +------------------+      +------------------+
       |
       v
  TERMINAL OUTPUT
  (tables / receipts / reports)

All monetary values are handled as integers in JPY (no decimal conversion needed), and the agent automatically formats amounts with the yen symbol and thousands separators for display. Tax calculations follow the Japanese consumption tax rules with support for both 10% standard rate and 8% reduced rate for food and beverages.

---

System Prompt Instructions

You are Stripe Japan Agent, a payment management assistant optimized for the Japanese market. Follow these rules precisely:

1. Validate STRIPE_SECRET_KEY before any API call. Detect whether it is a test key (sk_test_) or live key (sk_live_) and display a prominent [TEST MODE] or [LIVE MODE] indicator in all output.
2. Default currency is JPY. All amounts are integers (no decimals). Display with ¥ prefix and thousands separators: ¥12,800 not 128.00.
3. For PayPay payments, always create a PaymentIntent with payment_method_types: ["paypay"] and return the authorization URL for the customer to complete payment.
4. For konbini payments, always include payment_method_options.konbini.expires_after_days defaulting to 3 days. Display the payment code and store instructions.
5. Never log or display full card numbers, secret keys, or webhook secrets. Mask as ****4242 for cards and sk_****XXXX for keys.
6. When creating customers, accept and store both name (roman) and name_kana (furigana) fields for Japanese compliance.
7. Subscription commands must specify a price_id or allow inline price creation with --amount and --interval. Default interval is month.
8. Invoice generation must comply with the Tekikaku Invoice System: include registration number (T + 13 digits), tax breakdown by rate (8%/10%), and seller information.
9. Refund commands require confirmation for amounts over ¥50,000. Use --force to skip confirmation in automated pipelines.
10. Dispute responses should auto-collect available evidence (shipping tracking, customer correspondence, delivery confirmation) and format it for Stripe's dispute evidence object.
11. All webhook events must be verified using STRIPE_WEBHOOK_SECRET before processing. Reject unverified events with a clear error.
12. Rate limit API calls to 25 requests/second (Stripe's standard limit). Queue excess requests with exponential backoff.
13. For reporting commands, query the Stripe Reporting API and format results as terminal tables. Support date ranges with --from and --to flags.
14. Track payment method distribution (card vs PayPay vs konbini vs bank transfer) in all reports to help merchants understand customer preferences.
15. When handling errors from Stripe, translate error codes into actionable Japanese-market-specific advice. For example, card_declined should suggest trying PayPay or konbini as alternatives.
16. Support Stripe Connect for marketplace payouts when STRIPE_ACCOUNT_ID is set. Route commands to the connected account context.
17. Log all operations to ~/.clawhub/stripe-japan-agent/operations.log with timestamps, amounts, and anonymized customer references for audit purposes.

---

Environment Variables

Variable	Required	Default	Description
STRIPE_SECRET_KEY	Yes	--	Stripe secret key (test or live). Determines mode automatically.
STRIPE_WEBHOOK_SECRET	No	--	Webhook signing secret for event verification. Required for stripe listen.
STRIPE_ACCOUNT_ID	No	--	Connected account ID for Stripe Connect marketplace operations.
STRIPE_DEFAULT_CURRENCY	No	jpy	Default currency for all payment operations.

---

Commands

stripe charge

Create a one-time payment intent.

$ stripe charge 4800 --method card --customer cus_PxR4m8kJnW --description "Monthly box subscription"

 [LIVE MODE]
 Payment Intent Created
 ─────────────────────────────────────────
 ID:            pi_3QxY7mBkR2f8LNWZ1a2b3c4d
 Amount:        ¥4,800
 Currency:      JPY
 Status:        succeeded
 Method:        Visa ****4242
 Customer:      cus_PxR4m8kJnW (田中太郎)
 Description:   Monthly box subscription
 Created:       2026-03-01 14:23:07 JST
 Fee:           ¥163 (3.4%)
 Net:           ¥4,637

 Receipt URL: https://pay.stripe.com/receipts/...

stripe subscribe

Create or manage recurring subscriptions.

$ stripe subscribe cus_PxR4m8kJnW --price price_1QxMNBkR2f8LNWZ --trial-days 14

 [LIVE MODE]
 Subscription Created
 ─────────────────────────────────────────
 ID:            sub_1QxY8nCkR2f8LNWZ
 Customer:      cus_PxR4m8kJnW (田中太郎)
 Plan:          Premium Plan - ¥9,800/month
 Status:        trialing
 Trial Ends:    2026-03-15
 Next Invoice:  2026-03-15 - ¥9,800
 Payment:       Visa ****4242

 Subscription active. Customer will be charged after trial ends.

stripe invoice

Generate and send a compliant invoice.

$ stripe invoice cus_PxR4m8kJnW --items "Web制作費:¥150,000:10%,ドメイン費用:¥3,200:10%"

 [LIVE MODE]
 Invoice Created (Tekikaku Invoice Compliant)
 ─────────────────────────────────────────
 Invoice #:     INV-2026-0301-001
 Reg. Number:   T1234567890123
 Customer:      田中太郎 (cus_PxR4m8kJnW)
 Date:          2026-03-01

 Items:
   Web制作費                      ¥150,000   (税10%)
   ドメイン費用                     ¥3,200   (税10%)
 ─────────────────────────────────────────
 Subtotal:                        ¥153,200
 消費税 (10%):                     ¥15,320
 Total:                           ¥168,520

 Status: draft | Send with: stripe invoice send inv_1QxYAb...

stripe refund

Process a full or partial refund.

$ stripe refund pi_3QxY7mBkR2f8LNWZ1a2b3c4d --amount 2400 --reason "customer_request"

 [LIVE MODE]
 Refund Processed
 ─────────────────────────────────────────
 Refund ID:     re_3QxYBcDkR2f8LNWZ
 Payment:       pi_3QxY7mBkR2f8LNWZ1a2b3c4d
 Type:          Partial Refund
 Refund Amount: ¥2,400
 Original:      ¥4,800
 Remaining:     ¥2,400
 Reason:        Customer request
 Status:        succeeded
 ETA:           5-10 business days to customer account

stripe customers

List and search customers.

$ stripe customers --search "tanaka" --limit 5

 #  ID                   Name       Name (Kana)    Email                   Created      Payments
 1  cus_PxR4m8kJnW       田中太郎    タナカタロウ     [e-mail]      2025-08-12   ¥234,800
 2  cus_QyS5n9lKoX       田中花子    タナカハナコ     [e-mail]    2025-11-03   ¥89,200
 3  cus_RzT6o0mLpY       田中次郎    タナカジロウ     [e-mail]  2026-01-18   ¥12,400

 Showing 3 results for "tanaka" | Total customers: 1,247

stripe report

Generate financial reports.

$ stripe report --from 2026-02-01 --to 2026-02-28

 [LIVE MODE]
 Revenue Report: February 2026
 ═══════════════════════════════════════════

 Gross Revenue:     ¥2,847,300
 Refunds:           -¥123,400
 Net Revenue:       ¥2,723,900
 Stripe Fees:       -¥96,812
 Net Payout:        ¥2,627,088

 Payment Method Breakdown:
   Credit Card:     ¥1,823,100  (64.0%)  ████████████████
   PayPay:          ¥612,400    (21.5%)  █████
   Konbini:         ¥298,600    (10.5%)  ███
   Bank Transfer:   ¥113,200    (4.0%)   █

 Subscription MRR:  ¥1,240,000
 New Customers:     84
 Churn Rate:        2.1%

 Tax Summary:
   10% rate:  Taxable ¥2,234,000 → Tax ¥223,400
   8% rate:   Taxable ¥613,300   → Tax ¥49,064

stripe paypay

Create a PayPay payment link.

$ stripe paypay 3200 --description "オンラインコース受講料"

 [LIVE MODE]
 PayPay Payment Created
 ─────────────────────────────────────────
 ID:            pi_3QxYCeDkR2f8LNWZ
 Amount:        ¥3,200
 Method:        PayPay
 Status:        requires_action
 Expires:       2026-03-01 15:23:07 JST (1 hour)

 Authorization URL:
 https://checkout.stripe.com/c/pay/cs_live_a1b2c3d4...

 Share this link with the customer to complete PayPay payment.
 Webhook will fire on completion: payment_intent.succeeded

stripe konbini

Create a konbini (convenience store) payment.

$ stripe konbini 8900 --customer cus_PxR4m8kJnW --expires 3

 [LIVE MODE]
 Konbini Payment Created
 ─────────────────────────────────────────
 ID:            pi_3QxYDfEkR2f8LNWZ
 Amount:        ¥8,900
 Method:        Konbini
 Status:        requires_action
 Expires:       2026-03-04 14:23:07 JST (3 days)

 Payment Instructions:
 ┌─────────────────────────────────────┐
 │  Confirmation #:  12345-67890       │
 │                                     │
 │  Pay at any:                        │
 │  - Seven-Eleven (マルチコピー機)      │
 │  - Lawson (Loppi端末)               │
 │  - FamilyMart (Famiポート)           │
 │  - Ministop                         │
 └─────────────────────────────────────┘

 Email sent to: [e-mail] with payment code.

stripe disputes

Manage payment disputes and chargebacks.

$ stripe disputes --status open

 Open Disputes (3)
 ═══════════════════════════════════════════

 #  Dispute ID        Amount     Reason              Due Date     Payment
 1  dp_1QxYEgFkR2f8   ¥12,800   product_not_received 2026-03-08  pi_3Qx...abc
 2  dp_1QxYFhGkR2f8   ¥4,200    fraudulent           2026-03-05  pi_3Qx...def
 3  dp_1QxYGiHkR2f8   ¥8,900    duplicate            2026-03-12  pi_3Qx...ghi

 Total at risk: ¥25,900 | Win rate (last 90d): 68%

 Respond with: stripe disputes respond dp_1QxYEgFkR2f8 --evidence shipping_tracking

stripe dashboard

Display a real-time terminal dashboard.

$ stripe dashboard

 ╔═══════════════════════════════════════════════════════════╗
 ║  STRIPE JAPAN DASHBOARD          2026-03-01 14:30 JST    ║
 ╠═══════════════════════════════════════════════════════════╣
 ║                                                           ║
 ║  Today's Revenue     ¥187,400    (+12.3% vs yesterday)   ║
 ║  Successful Charges  47          (98.0% success rate)     ║
 ║  Failed Charges      1           (card_declined)          ║
 ║  Active Subs         312         (MRR: ¥1,240,000)       ║
 ║  Open Disputes       3           (¥25,900 at risk)       ║
 ║                                                           ║
 ║  Last 5 Transactions:                                     ║
 ║  14:28  ¥4,800   Visa ****4242    succeeded               ║
 ║  14:15  ¥3,200   PayPay           succeeded               ║
 ║  14:02  ¥8,900   Konbini          pending                 ║
 ║  13:48  ¥12,400  Visa ****1234    succeeded               ║
 ║  13:31  ¥2,100   PayPay           succeeded               ║
 ║                                                           ║
 ╚═══════════════════════════════════════════════════════════╝

---

Workflow Diagram

  PAYMENT LIFECYCLE
  =================

  Customer Order
       |
       v
  +----------+     Card?     +------------------+
  | Method   |-------------->| PaymentIntent    |---> Instant confirm
  | Selection|               | (card)           |
  +----------+               +------------------+
       |
       | PayPay?    +------------------+
       +----------->| PaymentIntent    |---> Auth URL ---> Customer scans
       |            | (paypay)         |       QR code ---> Webhook confirm
       |            +------------------+
       |
       | Konbini?   +------------------+
       +----------->| PaymentIntent    |---> Payment code ---> Customer pays
       |            | (konbini, 3 day) |       at store   ---> Webhook confirm
       |            +------------------+
       |
       | Transfer?  +------------------+
       +----------->| Invoice          |---> Bank details ---> Customer transfers
                    | (bank_transfer)  |                  ---> Auto-reconcile
                    +------------------+
                           |
                           v
                    +------------------+
                    | Payment Complete |
                    | -> Receipt       |
                    | -> Fulfillment   |
                    | -> Analytics     |
                    +------------------+

---

Error Handling

Error	Cause	Solution
AUTH_ERROR: No such API key	Invalid or revoked STRIPE_SECRET_KEY	Verify key at dashboard.stripe.com/apikeys. Ensure you are using the correct test/live key.
CARD_DECLINED: insufficient_funds	Customer's card has insufficient balance	Suggest PayPay or konbini as alternative. Use stripe charge --method paypay to retry with PayPay.
KONBINI_EXPIRED: Payment window closed	Customer did not pay at konbini within the expiry window	Create a new konbini payment with stripe konbini. Consider extending --expires to 5 or 7 days.
WEBHOOK_SIGNATURE_INVALID	Mismatched STRIPE_WEBHOOK_SECRET or tampered payload	Regenerate webhook secret at dashboard.stripe.com/webhooks. Update STRIPE_WEBHOOK_SECRET env var.
AMOUNT_TOO_SMALL: Below minimum	JPY charge below Stripe's minimum (¥50)	Ensure charge amount is at least ¥50. For smaller amounts, batch multiple items.
CURRENCY_MISMATCH: Expected jpy	Attempting to charge in non-JPY currency without override	Set amount in JPY (integer, no decimals) or override with --currency usd if intentional.
DISPUTE_DEADLINE_PASSED	Evidence submission deadline exceeded	Future disputes require response within 7-21 days. Set up stripe disputes --watch for alerts.

---

Data Storage

All persistent data is stored under ~/.clawhub/stripe-japan-agent/:

Path	Purpose	Format	Retention
operations.log	Audit log of all payment operations	JSON lines	1 year, rotated monthly
webhooks.log	Received webhook events	JSON lines	90 days
reports/	Generated financial reports	JSON + CSV	Permanent
dispute-evidence/	Collected dispute response evidence	Mixed (PDF, JSON)	Until dispute resolved
config.json	Agent configuration and preferences	JSON	Permanent

---

Comparison Table

Feature	stripe-japan-agent	Stripe Dashboard	Square JP	PayJP	GMO Payment
PayPay Support	Yes (native)	Yes	No	No	Yes
Konbini Payments	Yes (all chains)	Yes	No	Yes	Yes
CLI-native Interface	Yes	No (web only)	No	No	No
Tekikaku Invoice	Auto-generated	Manual setup	No	No	Yes
Subscription Mgmt	Full lifecycle	Yes	Limited	Yes	Limited
Dispute Automation	Evidence collection	Manual	Basic	No	Manual
Multi-currency	JPY default + all	Yes	JPY only	JPY only	JPY + few
Webhook Monitoring	Terminal real-time	Web dashboard	Web only	Web only	Web only
Tax Rate Handling	8% + 10% auto	Manual config	N/A	Manual	Manual
Financial Reports	CLI + CSV export	Web dashboard	Web only	Web only	Web only
Setup Complexity	1 env var + go	Web registration	Web + device	API key	Complex
Fees (domestic card)	3.4%	3.4%	3.25%	3.0%	3.2-3.5%

---

FAQ

1. Do I need a Stripe account registered in Japan? Yes. To accept JPY payments and use Japan-specific methods (PayPay, konbini), your Stripe account must be registered as a Japanese business entity or sole proprietor.

2. How do I switch between test and live mode? The agent auto-detects based on your key prefix. Use sk_test_ keys for testing and sk_live_ keys for production. A clear [TEST MODE] or [LIVE MODE] badge appears in all output.

3. Are konbini payments instant? No. The customer receives a payment code and has a configurable window (default 3 days) to pay at a convenience store. A webhook event fires when payment is completed.

4. What convenience stores are supported? Seven-Eleven, Lawson, FamilyMart, Ministop, Daily Yamazaki, and Seicomart. The payment code works at all chains automatically.

5. How does PayPay integration work? The agent creates a PaymentIntent with PayPay method, which returns an authorization URL. The customer opens this URL, scans a QR code in their PayPay app, and confirms payment. A webhook notifies you of success.

6. What is the Tekikaku Invoice System? Since October 2023, Japan requires qualified invoices for consumption tax credit. The agent auto-generates compliant invoices with your registration number (T + 13 digits), itemized tax rates, and required seller information.

7. How are JPY amounts handled? JPY is a zero-decimal currency. All amounts are integers: ¥4,800 is sent to Stripe as 4800, not 48.00. The agent handles this automatically so you never deal with decimal conversion.

8. Can I process refunds for konbini payments? Yes, but konbini refunds are deposited to the customer's bank account (not returned to the store). You will need the customer's bank details, which Stripe collects during the refund flow.

9. How do I handle the 8% reduced tax rate? When creating invoices, specify the tax rate per item: --items "食品:¥1,000:8%,雑貨:¥2,000:10%". The agent calculates and displays tax breakdown per rate category.

10. What happens if a webhook fails? Stripe retries failed webhooks with exponential backoff for up to 3 days. The agent logs all received events. Use stripe webhooks retry to manually re-process a specific event.

11. Can I use this for marketplace payouts with Stripe Connect? Yes. Set STRIPE_ACCOUNT_ID to route commands to a connected account. Use stripe charge --on-behalf-of acct_XXX for platform charges with automatic fee splitting.

12. How do I export data for my accountant? Use stripe report --from YYYY-MM-DD --to YYYY-MM-DD --format csv to generate CSV files compatible with freee, MoneyForward, and other Japanese accounting software.