Skip to content

Supporter payments with PAY.JP

With payments = payjp, local users subscribe to monthly or yearly plans on this server’s payment page, and the plan’s role is granted and removed as the payment state changes. When tips are enabled, users also pay one-time tips on PAY.JP’s hosted page (see Tips). The deployment keys are described in the configuration reference. For the program as a whole (plans, roles, the list of members), see supporters.md. An administrator enables the program and creates plans in the administration. This setting only lets the server talk to PAY.JP.

One server can use only one provider. To switch from Stripe to PAY.JP (or the reverse), ask the existing subscribers to subscribe again with the new provider.

PAY.JP has API v1 and v2. v2 has no recurring-billing API yet, so the server uses the recurring billing of API v1 (Plan and Subscription). v1 has neither a hosted payment page nor a customer portal, so this server serves pages in their place. Tips are one-time payments on API v2, which has a hosted payment page; see Tips. PAY.JP allows both versions on one account with the same keys.

How a subscription works shows in a diagram how the payment page, the webhook, the reconciliation, the plan’s role, and the income fit together.

  • Plans: For each price the server creates a Plan whose ID is my_<plan ID>_<month|year>_<amount> (metadata.my_plan_id). A PAY.JP Plan cannot change its amount, so changing the amount creates a new Plan, and the old Plan is not deleted but gets metadata.my_archived=1. Subscriptions on the old Plan renew at its amount. Do not edit or delete these Plans in the administration of PAY.JP. The only currency is the Japanese yen, and amounts are 50 to 9,999,999 yen.
  • Subscribing: The server sends the user’s browser to its own payment page (/payments/pages/payjp/checkout). The page shows the card fields of payjp.js (PAY.JP’s iframe) and runs 3-D Secure authentication when it creates the token (the iframe type). The server accepts only a token whose 3-D Secure has completed (three_d_secure_status is verified or attempted), adds the card to the customer as the default card (for the first time with the ID my_<the server's subscription ID>), and creates a subscription with the server’s subscription ID in metadata.my_subscription_id. The first charge happens when the subscription is created. The page URL is short-lived and carries a state signed by the server (valid for 1 to 2 hours from creation). A user who leaves the page and starts again, on the same plan or another, gets a new URL for the plan they asked for now. An earlier URL keeps working until it expires, and whichever page is paid first makes the only subscription: the others go on to it. If an earlier page was paid already, the user goes to the return screen and gets no new URL. A signed URL cannot be withdrawn, so a page stays payable after its pending subscription closes (its plan retired, its account deleted). A payment on it buys nothing: the server deletes the subscription and refunds its charges in full (PAY.JP accepts a refund for 180 days after the sale). API v1 takes no idempotency key, so while one submission of the page creates the subscription, the server marks the checkout as in progress in the database: a second submission (a double click, another tab, or another server process behind the same load balancer) waits up to 30 seconds and then goes on to the subscription that the first one created. The mark expires after 5 minutes if the process that held it stopped.
  • The card and payment history page (in place of Stripe’s customer portal): From their subscription screen, a subscriber opens /payments/pages/payjp/portal to change the card and check recent payments (the URL expires in one hour). The form starts with the email address of the PAY.JP customer, which is the address entered at the first payment, not a later change of the account’s address. Changing the card resumes a subscription stopped by a failed payment and charges at once. Cancelling and changing plans are done on this server’s subscription screen.
  • Payment failure: PAY.JP pauses (paused) a subscription whose renewal charge failed, and does not retry. The server treats the pause as a late payment and keeps the role for a grace period of 7 days from the time of the pause. If the subscriber changes the card in that time, the subscription resumes; if not, the role is removed after 7 days (on the PAY.JP side the subscription stays paused and is not charged).
  • Plan changes: An upgrade charges the difference for the rest of the current period, prorated, as a one-time charge (no charge under 50 yen), replaces the plan, and charges the new plan’s full amount at the end of the period (the start of the period does not move). If the charge for the difference is declined, the plan does not change. A downgrade, and a change from yearly to monthly, switch at the end of the period with next_cycle_plan.
  • Reading state back: The server treats a webhook as a signal and reads the subscription and the money movements back from the PAY.JP API to decide the state. In addition, a reconciliation every payments_reconcile_interval reads the event list, the money movements, and a sweep of all subscriptions, and repairs any webhook the server missed.
  • Income: For each payment the server records the gross amount, the fee (computed from the charge’s fee_rate, rounding down below one yen), and the net. A refund and a chargeback record the returned fee as a negative fee. When a term closes and a statement is issued, the difference between the statement’s fee and the server’s computation (the fees of the subscriptions’ charges and of the term’s tips) is recorded as a fee movement (its ID is the statement’s ID), so that the term’s fee total matches the statement. A statement covers the fees of the whole account, so use a PAY.JP account dedicated to this server.
  • Dates: Income dates are counted in Japan time.

The server sends at most 20 requests per second (2 in test mode), API v1 and v2 together. That stays within PAY.JP’s rate limit (for secret-key requests, 30 per second in live mode and 2 in test mode). On 429 the server waits 1 second, doubling each time, and retries up to 3 times. In test mode a single reconciliation is slow (about 8 minutes at the limit of 1,000 requests). A continuation job takes over, so no action is needed.

Tips (see supporters.md) use PAY.JP’s API v2 with the same keys and webhook token as the subscriptions. PAY.JP lists tipping among the goods it finds hard to approve: whether your account may take tips is for you to settle with PAY.JP under its review and its terms.

  • Paying: The server creates a Checkout Session (mode=payment) of the one amount, by card only, that expires in one hour, and sends the user to its page on PAY.JP (an https page on pay.jp; the server refuses any other address). The server’s tip ID is in the session’s client_reference_id and in metadata.my_tip_id of the session and of its PaymentFlow. The creation carries an Idempotency-Key, so a retry gets the same session. PAY.JP runs 3-D Secure on the hosted page when the card company asks for it. A tip is paid when its session is complete and its PaymentFlow has succeeded. When a user starts another tip, the server expires the open session first (POST /v2/checkout/sessions/{id}/expire); if the user paid it in the meantime, that payment is recorded instead.
  • Income: The money of the tips comes from the account’s payment transactions of API v2: a payment (its ID is the PaymentFlow’s), a refund, a chargeback, and the cancellation of a chargeback, each with the fee that PAY.JP reports. A refund and a chargeback record the returned fee as a negative fee, as for the subscriptions.
  • Disputes: PAY.JP sends an event only when a dispute opens. Each reconciliation also reads the disputes that ended in your favour (status cancel), and records the cancellation of a chargeback that the payment transactions do not report themselves. A dispute that closed without a chargeback (an inquiry) records nothing.
  • Refunds: Refund a tip in the PAY.JP dashboard. A refund in full and a chargeback are recorded with the tip; a partial refund only in the income.

Card numbers, expiry dates, and security codes are entered only inside PAY.JP’s iframe, which payjp.js shows. This server’s page and script never touch them. The server receives only the token ID that payjp.js created and the cardholder name and email address that 3-D Secure needs. The server stores only PAY.JP object IDs (cus_, sub_, ch_, Plan IDs, event IDs, and the Checkout Sessions, PaymentFlows, refunds, and disputes of the tips), amounts, periods, and states. The card of a tip is entered on PAY.JP’s own page, which this server never serves. It does not store card numbers, last four digits, or expiry dates (the card page only reads the last four digits, the expiry date, and the customer’s email address from PAY.JP and shows them). Webhook bodies and PAY.JP responses are kept in neither the logs nor the database.

The payment page is served from this server’s origin, so it is built with PCI DSS v4’s management of payment-page scripts (requirement 6.4.3) and detection of tampering (requirement 11.6.1) in mind.

  • The page is a part of the web client, built into the server’s binary: it loads the web client’s own scripts from this server, each with its Subresource Integrity, and https://js.pay.jp/v2/pay.js, which PAY.JP serves and updates. It loads no analytics or advertising script.
  • Every release carries payment-scripts.json, the list of every script the page loads: each script of the web client with its hash, and payjp.js. The page shares scripts with the rest of the web client, so the list changes from release to release; keep the list of the release you run. The server refuses to start with a build whose list does not match its scripts.
  • The page always carries its own Content-Security-Policy (script-src only this server and https://js.pay.jp, frame-src only https://js.pay.jp and https://api.pay.jp, form-action 'self', frame-ancestors 'none'), Referrer-Policy: no-referrer, Cache-Control: no-store, and X-Content-Type-Options: nosniff. No setting changes the CSP. Form submissions are accepted only from the same origin.

As a result, the operator’s scope is expected to be that of a merchant who leaves payment entry to PAY.JP’s iframe (SAQ A). Check the scope that applies and the type of self-assessment questionnaire against PAY.JP’s guidance and your card brands’ requirements. When you do, it helps to keep a record of these points: the payment page URLs (/payments/pages/payjp/checkout and /portal), the list of scripts the page loads (payment-scripts.json of the release), the page’s CSP, and that traffic to the server uses TLS (the reverse proxy’s configuration).

  1. Create a PAY.JP account and start in test mode. Charging in live mode needs a production application and a review.
  2. Check “API settings > 3-D Secure” in the PAY.JP dashboard. The server asks for 3-D Secure each time it creates a token, so you may also choose to require 3-D Secure for all token creation.
  3. The page of the commerce disclosure is set in this server’s administration (see supporters.md).

Under “API” in the PAY.JP dashboard, check these two keys. The prefix of a key sets the mode, and test keys charge nothing. Both keys must be in the same mode.

Key Example Use
Secret key sk_test_... / sk_live_... The server calls the API with it. It is also the source of the key that signs page URLs
Public key pk_test_... / pk_live_... payjp.js on the payment and card pages

Pass the secret key in the environment variable MY_PAYMENTS_PAYJP_SECRET_KEY (or the path of a file in MY_PAYMENTS_PAYJP_SECRET_KEY_FILE). It cannot be written in the configuration file. If the secret key leaks, reissue it in the dashboard and redeploy with the new key. The URLs of payment and card pages that were open before the redeploy stop working.

Under “Settings > Webhook” in the PAY.JP dashboard, add a destination. Register test mode and live mode separately.

  • URL: https://<server domain>/payments/webhooks/payjp
  • Mode: the same as the keys

A PAY.JP webhook identifies its sender with the account’s origin token (whook_..., in the header X-Payjp-Webhook-Token). Pass the token shown in the dashboard in the environment variable MY_PAYMENTS_PAYJP_WEBHOOK_TOKEN (or _FILE). The endpoint compares the token in constant time, and rejects a test event received with a live key (and the reverse) with 400. There is no signature or timestamp, so anyone who knows the token can send a notification, but the server never writes state from the contents of a notification; it only reads the state back from PAY.JP.

The server uses these events (other types are accepted but not recorded).

  • subscription.created, subscription.updated, subscription.deleted, subscription.paused, subscription.resumed, subscription.canceled, subscription.renewed
  • charge.succeeded, charge.failed, charge.refunded
  • dispute.created
  • statement.created
  • For tips (API v2): checkout.session.completed, checkout.session.expired, payment_flow.succeeded, refund.created, refund.updated, refund.failed, and dispute.created

The server tells the events of API v1 and v2 apart by their shape, so both versions go to the same URL with the same token.

PAY.JP resends a notification only every 3 minutes, at most 3 times, and a notification past that does not arrive until you resend it from the dashboard. The reconciliation repairs what was missed, so setting payments_reconcile_interval to 1 hour is recommended. The state of the provider (the mode, when the last webhook arrived, and the result of the last reconciliation) is shown in the “Payment provider” section of /admin/supporters in the administration.

Terminal window
MY_PAYMENTS=payjp
MY_PAYMENTS_PAYJP_SECRET_KEY=sk_test_...
MY_PAYMENTS_PAYJP_PUBLIC_KEY=pk_test_...
MY_PAYMENTS_PAYJP_WEBHOOK_TOKEN=whook_...
# The recommended reconciliation interval (15m to 168h, default 6h) and the most requests one reconciliation sends (default 1000)
MY_PAYMENTS_RECONCILE_INTERVAL=1h
MY_PAYMENTS_RECONCILE_MAX_REQUESTS=1000

my config check verifies the configuration.

Start with test keys. Test mode and live mode have separate Plans, customers, subscriptions, webhooks, and tokens. To go live, register the webhook in live mode, replace the keys and the token with the live ones, and redeploy. The plans’ Plans are created anew in the live account.

Test cards (PAY.JP documentation):

Number Behavior
4242 4242 4242 4242 Succeeds
4000 0000 0008 0319 The card can be registered but the charge is declined (a failed subscription, and a failed resume after a card change)
4000 0000 0000 4012 The card can be registered but the charge fails as expired
4000 0000 0000 0002 Registering the card (creating the token) is declined

Use a future expiry date; the security code and the name are arbitrary. In test mode, PAY.JP’s test authentication screen for 3-D Secure lets you choose the result.

To try a renewal quickly, set the subscription’s trial_end a few minutes ahead with the API. The renewal charge runs some minutes after that time, not at it. Another update of trial_end while the first is due restarts the wait. To try a payment failure and the grace period, subscribe, change the card on the card page to the card that is declined (4000 0000 0008 0319), and then let the subscription renew.

PAY.JP webhooks go to a public URL, so to receive them on a server on your machine, expose the port through a tunnel (cloudflared, ngrok, and the like) and register that URL as a test-mode destination. payjp listen --forward-to http://localhost:8080/payments/webhooks/payjp of payjp-cli is expected to forward events as well, but whether it can forward v1 events has not been verified.

Open the payment and card pages on this server’s origin (they also work on http://localhost:8080, but the behavior of payjp.js and 3-D Secure varies with the browser’s settings).

  • A reconciliation failure of kind permission means a wrong secret key.
  • duplicate_charge in the warnings of the “Payment provider” section means that the server could not finish refunding a payment for a closed subscription. The log line a second subscription could not be canceled and refunded names the subscription, and each reconciliation tries again, also after the subscription is deleted. Refund the charge in the dashboard if it goes on: the next try finds it refunded and clears the warning, as long as PAY.JP still lists the charges of the deleted subscription (see Items to verify). A charge more than 180 days old cannot be refunded: the server logs it and goes on.
  • Other refunds are handled in the PAY.JP dashboard. A full refund and a chargeback remove the role and delete the subscription at once, and a partial refund does not remove the role.
  • A chargeback cancellation of a subscription’s charge is not recorded automatically, because API v1 has neither an event nor an API for it (one of a tip is, see Tips). When one happens, record the cancelled amount on the income screen of the costs page (finance). The role is not restored automatically.
  • PAY.JP’s paid-plan fees and transfer fees are not subtracted from the income. Record them as costs in finance.
  • When reconciliations often hit the request limit, raise payments_reconcile_max_requests or lengthen payments_reconcile_interval.

An upgrade charges the prorated difference first and moves the plan only after that charge succeeds. When the charge is declined, the plan stays and the user sees an error with the way to update the card, with no grace period and no failed-payment notification, and trying again with a good card charges once. If the plan fails to move after the charge, trying again does not charge again. A difference below the 50 yen minimum, and a change to the yearly price of the same plan, which has no positive difference, charge nothing now and move at once; the new price is charged at the end of the period, and a failure then is a failed renewal.

The following behaviors are not settled by PAY.JP’s documentation or by test mode.

  • How the fee returned by a chargeback is computed, and whether a term’s statement matches the server’s fees (test mode showed a fee rounded down, and a refund’s fee computed from its amount).
  • What a real chargeback does: PAY.JP documents no way to cause one in test mode and no body for dispute.created. A test send of the event from the dashboard is answered with 200 and changes nothing.
  • How far back the event list reaches.
  • Whether deleting a Plan affects existing subscriptions (the server never deletes one), and the maximum length of a Plan ID.
  • Whether the CSP report on loading the payment page matters: pay.js applies an inline style against style-src 'self', while the card fields and 3-D Secure work in Chromium. Other browsers were not checked.
  • Whether payjp-cli can forward v1 events.
  • That a charge of a customer’s saved card asks for no 3-D Secure unless the request does. A declined charge is listed by GET /v1/charges with paid: false, and the server ignores one that is not paid.
  • For tips on API v2, which were built from PAY.JP’s guides and official SDK and not yet tried in test mode: that PAY.JP sends the events of v2 to the same destination with the same token as those of v1; that the hosted page is on pay.jp or one of its subdomains; that the creation of a Checkout Session honours Idempotency-Key; that a payment transaction’s resource_id is the PaymentFlow of a payment, the refund of a refund, and the dispute of a chargeback and of its cancellation; that the lists are newest first with starting_after and ending_before; the signs of a transaction’s amount and fee; and that a term’s statement of v1 includes the fees of v2.
  • That GET /v1/charges with subscription still lists the charges of a deleted subscription. The server refunds before it deletes, so only a try after a refund that failed for good relies on this. The API reference documents the filter and says nothing about deleted subscriptions. If the list comes back empty, the server reports a failure instead of a refund, and duplicate_charge stays even after the charge is refunded by hand.

For LLMs and coding agents:this page as Markdown, llms.txt,llms-full.txt, llms-small.txt

Analytics on this site