Your end users pay you, on a Stripe account of yours. Each application has its own payment connection; until it has one, plans can be published and activated by hand, but nobody can check out. This page covers the connection made with your own Stripe keys.
Charges are made on your Stripe account, and ShipRev adds no application fee to them. Through the connection, ShipRev creates the products and prices of your published plan versions, opens checkout and the billing portal for your end users, and receives Stripe's events about their payments.
Connect with your Stripe keys
You need an owner or admin role in your organization. In the application's operator console, open Settings, Payment Gateway.
Save your secret key
Choose Configure Stripe and paste your Stripe secret key, sk_test_… or sk_live_…. The key decides the mode: a test key makes a test-mode connection. The publishable key is optional. Save.
Register the webhook endpoint in Stripe
Once saved, the page shows the connection's webhook address, ending in /hooks/stripe/ and the connection's ID. In your Stripe Dashboard, add an endpoint with this address, in the same mode as the key, and select the events listed below.
Save the signing secret
Copy the endpoint's signing secret, whsec_…, from Stripe. Back on Payment Gateway, choose Update Keys, paste the secret key again together with the signing secret, and save. The connection keeps its ID, so the webhook address does not change.
Test it
Choose Test Connection. It asks Stripe for the account the key belongs to and shows it.
Without the signing secret, ShipRev cannot check that an event comes from Stripe and rejects every event. Checkouts would then be paid on Stripe but stay pending in ShipRev.
When the connection is saved, plan versions you published before it are synced to the account in the same request; see What publishing does.
The same steps work through the Management API, with POST /mgt/v1/projects/{projectId}/payments/connection to save the keys (pass test_mode: false with a live key; the API's default is test mode), GET /mgt/v1/projects/{projectId}/payments/connection to read the connection and its ID, and POST /mgt/v1/projects/{projectId}/payments/connection/probe to test it.
The events to send
| Event | What ShipRev does with it |
|---|---|
checkout.session.completed | Activates the subscription a customer paid for, or credits a wallet top-up |
checkout.session.expired | Clears a checkout the customer abandoned |
invoice.paid | Records a renewal or a plan change as paid |
invoice.payment_failed | Records a failed payment on a subscription |
customer.subscription.updated | Follows a plan change, and a cancellation scheduled or undone in Stripe's billing portal |
customer.subscription.deleted | Ends the subscription in ShipRev when it ends in Stripe |
payment_intent.succeeded | Credits the wallet with a successful automatic charge |
payment_intent.payment_failed | Records a failed automatic wallet charge |
payment_intent.requires_action | Records as failed an automatic wallet charge that needs the payer to confirm it; automatic charges are then turned off for that organization |
The three payment_intent events matter once your end users turn on automatic wallet top-ups, described in Wallet and top-ups. Other event types are accepted and ignored.
Check that events arrive
Payment Gateway lists the recent webhooks the application received, with the result of each: processed, ignored, rejected or failed, and the reason. They are kept for 30 days. The same list is available with GET /mgt/v1/payments/webhook-events, for the application of your operator session.
| What you see | Usual cause |
|---|---|
| Nothing at all | The endpoint in Stripe has a different address, is in the other mode, or does not send the event |
| Rejected, the signature did not match | The signing secret belongs to another endpoint, or to the other mode |
| Rejected, no signing secret is saved | Step 3 was skipped |
Stripe resends an event that was not answered with success, so a redelivered event is not counted twice: ShipRev recognizes the event and the invoice it carries. More about how payments are recorded is in Invoices.
Test mode and going live
Rehearse with a test key and Stripe's test cards. To go live, choose Update Keys and save your live secret key, then register the same webhook address on a live-mode endpoint in Stripe and save its signing secret.
A published plan version is synced once and keeps the Stripe price it was given. Versions synced while the connection used test keys keep their test-mode prices after you switch to live keys, and checkout on them fails. Publish a new version of each plan you sell once the live keys are saved, so that its price is created on the live account.
Disconnect Stripe on the same page ends the connection. From then on checkout, plan changes and top-ups are refused with PAYMENT_PROVIDER_NOT_CONFIGURED until a connection is saved again.