Stripe payments for GoCommerce

What it does

Configuration

Two settings are required: the secret key and the webhook endpoint’s signing secret. Set them in Config from your own main(), or leave Config empty and type them under Settings › Payment methods in the admin.

The module reads its Config struct, not the environment. The variable names are the ones the package’s own example or the reference binary uses; in your own main() you choose where each value comes from. Where a setting has a panel label, the admin’s settings drawer can hold it too, and a value typed there wins over Config.

Setting it up

1. Register the webhookIn Stripe, add an endpoint at https://your-api-host/api/checkout/stripe/webhook for payment_intent.succeeded and payment_intent.payment_failed, and copy its signing secret.
2. Install the moduleImport it and pass stripe.New to gocommerce.New, as below — or run the reference binary with -gateways, which installs every payment module idle.
3. Give it the keysSecret key and webhook signing secret, in Config or under Settings › Payment methods. A key typed into the panel counts on the next request, with no restart.
4. Take a paymentPOST /api/checkout/stripe answers with the order and a client_action intent carrying the client_secret. The storefront confirms the payment with it; the webhook marks the order paid.

import (
	"os"

	"github.com/itswadesh/gocommerce/core"
	stripe "github.com/itswadesh/gocommerce/ext/payments-stripe"
)

app, err := gocommerce.New(cfg,
	stripe.New(stripe.Config{
		SecretKey:     os.Getenv("STRIPE_SECRET_KEY"),
		WebhookSecret: os.Getenv("STRIPE_WEBHOOK_SECRET"),
	}),
)

How it works

• One route, owned by the engine

  Stripe calls POST /api/checkout/stripe/webhook. The engine hands the module the request body untouched, because the signature is over the exact bytes Stripe sent.

• Signed and timed

  Stripe-Signature’s t=…,v1=… is checked as an HMAC-SHA256 over the timestamp, a dot and the body, in constant time. A timestamp more than five minutes from now is refused as a replay, as is a missing or wrong signature (400).

• Each event once

  The module claims Stripe’s event id with INSERT … ON CONFLICT DO NOTHING in its own table — atomic even across several instances. A redelivered event is answered 200 and changes nothing.

• A failed update is retried

  If marking the order paid fails, the module releases its claim and answers 500, so Stripe’s retry finds work to do rather than a record saying it was handled.

• Refunds keep Stripe’s id

  A refund from the admin posts to Stripe’s refunds endpoint against the order’s PaymentIntent, for the amount asked. The refund id is recorded on the refund row; a refund Stripe marks failed comes back as an error, id included.

• Metadata that cannot collide

  The order id and number travel in the PaymentIntent’s metadata. Extra data the storefront sends at checkout goes in under client_… keys, so it cannot overwrite what the webhook reads. The order’s email is passed as receipt_email.

What it does not do

Read these before an order depends on it. No store is known to run GoCommerce in production yet, so these come from the code, not from anyone’s experience.

• Two event typesOnly payment_intent.succeeded and payment_intent.payment_failed change an order. Every other event is acknowledged; charge.refunded is logged and nothing more.
• Dashboard refunds are not appliedA refund made in Stripe’s dashboard is logged, and the GoCommerce order does not change. Refund from the admin if the order and Stripe are to agree.
• No disputesDisputes and chargebacks are not handled. Their events are acknowledged and ignored, so the order keeps reading as paid.
• The storefront confirmsThe module returns a client secret, not a page. Collecting card details and confirming the PaymentIntent is the storefront’s job.
• The store’s one currencyThe PaymentIntent is created in the store’s single settlement currency, unconverted. Which currencies and methods are offered is decided in Stripe.