Paddle payments for GoCommerce

What it does

Configuration

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

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. Add a notification destinationIn Paddle, send notifications to https://your-api-host/api/checkout/paddle/webhook — transaction.completed and transaction.payment_failed at least — and keep its secret.
2. Empty the tax ratesPaddle works out the tax. Leave GoCommerce’s tax rates empty so the order total is the price the shopper pays.
3. Install and configurePass paddle.New to gocommerce.New as below, or run the reference binary with -gateways and fill in Settings › Payment methods. Tick Sandbox while testing.
4. Take a paymentPOST /api/checkout/paddle answers with a redirect intent whose url is Paddle’s checkout. transaction.completed marks the order paid.

import (
	"os"

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

app, err := gocommerce.New(cfg,
	paddle.New(paddle.Config{
		APIKey:        os.Getenv("PADDLE_API_KEY"),
		WebhookSecret: os.Getenv("PADDLE_NOTIFICATION_SECRET"),
		Sandbox:       true,
	}),
)

How it works

• Signed and timed

  Paddle-Signature’s ts=…;h1=… is checked as an HMAC-SHA256 over the timestamp, a colon and the raw body. Several h1 values pass during a secret rotation; a timestamp outside the tolerance, early or late, is refused.

• Each event once

  Claims are keyed on Paddle’s event_id with INSERT … ON CONFLICT DO NOTHING, atomic across instances. A redelivery is answered 200 and changes nothing.

• A failed update is retried

  If marking the order paid fails, the claim is released and the webhook answers 500, so Paddle’s retry finds work to do.

• One line per order

  Paddle’s items belong to its own catalogue, so the module sends one ad-hoc line carrying the order total rather than mirroring the order into Paddle products. The order keeps the breakdown.

• Refunds as adjustments

  A refund reads the transaction back to find its line, then creates a refund adjustment for exactly the amount asked — always typed partial, so Paddle cannot turn a partial refund into a full one. The adjustment id is recorded; a rejected one comes back as an error.

• Amounts as strings

  Amounts go to Paddle as integer strings in minor units, never as floats, so nothing picks up a rounding error on the way through JSON.

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.

• Tax is Paddle’sLeave GoCommerce’s tax rates empty. The module does not check, and a store that configures both charges tax twice.
• One line, one tax categoryEvery order is sent as a single line with Paddle’s standard tax category, whatever the products in it are.
• Needs a checkout URLA transaction that comes back without one is refused, with a note to check that the Paddle account has an approved default payment link.
• Adjustments are only loggedadjustment.created and adjustment.updated are logged, not applied. A refund made in Paddle’s dashboard does not change the GoCommerce order.
• Orders, not subscriptionsThe module sells an order once. Events for anything this store did not start, such as a renewal billed in Paddle, are acknowledged and ignored.