Clover integration in Go

What it does

Configuration

Three settings are required: the merchant ID, the Ecommerce private token and the webhook 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. Set the webhook in CloverIn the Clover dashboard, under Settings › Ecommerce › Hosted Checkout, set the webhook URL to https://your-api-host/api/checkout/clover/webhook and generate the signing secret.
2. Install the modulePass clover.New to gocommerce.New, as below, or run the reference binary with -gateways, which installs every payment module idle.
3. Give it the keysMerchant ID, private token, signing secret and the account’s currency, in Config or under Settings › Payment methods, with a return URL if the storefront sends none.
4. Take a paymentPOST /api/checkout/clover answers with a redirect intent whose url is Clover’s Hosted Checkout page. The PAYMENT webhook marks the order paid.

import (
	"os"

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

app, err := gocommerce.New(cfg,
	clover.New(clover.Config{
		MerchantID:    os.Getenv("CLOVER_MERCHANT_ID"),
		PrivateToken:  os.Getenv("CLOVER_PRIVATE_TOKEN"),
		WebhookSecret: os.Getenv("CLOVER_WEBHOOK_SECRET"),
	}),
)

How it works

• One route, owned by the engine

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

• Signed and timed

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

• The session’s amount is the check

  The webhook carries no amount, so the module compares the amount and currency its session asked for with the order’s. An order whose total changed since is logged as an error and not settled, for an operator who can see both sides.

• Each outcome once

  A decline and then an approval can arrive for one session, so the claim is on the payment and its outcome, in the module’s own table with ON CONFLICT DO NOTHING. A redelivery is answered 200 and changes nothing; a decline arriving after the approval leaves the order paid.

• A failed update is retried

  If marking the order paid or failed does not go through, the module releases its claim and answers 500, so Clover’s retry finds work to do.

• Refunds, whole or in part

  A refund from the admin posts to Clover’s refunds endpoint against the payment id the webhook recorded, for the amount asked. Clover’s refund id is kept; a refund Clover marks failed or cancelled comes back as an error with its reason.

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.

• USD and CAD onlyHosted Checkout is offered in the United States and Canada, and charges in the merchant account’s currency. The store’s settlement currency has to be that one; any other order is refused at checkout.
• The return proves nothingThe shopper’s return to the storefront does not settle the order. Until the webhook arrives the order reads unpaid, and an order with no working webhook stays that way.
• A changed total waits for a personAn approved payment whose session asked for a different amount or currency than the order now holds is acknowledged and not applied. The order stays unpaid until an operator reconciles it.
• Refunds need the webhook firstUntil the webhook records Clover’s payment id, the order holds only the checkout session, which Clover cannot refund; the module says so rather than try.
• Dashboard refunds and disputesThe module acts on PAYMENT notifications only. A refund made in Clover’s dashboard, or a dispute, does not change the GoCommerce order.
• Nothing travels with the sessionExtra data the storefront sends at checkout is not passed to Clover: a Hosted Checkout session has nowhere to carry it. The order’s email goes as the customer’s.

Related modules

Each is a directory under ext/, imported the same way. Where this one fits in the store: Checkout and payments in GoCommerce.

• Creem integration in Go Sell through Creem as merchant of record from a GoCommerce store: the placeholder product, keys, webhook URL, full-only refunds and the module’s limits.
• Helcim integration in Go Take card payments through Helcim’s HelcimPay.js in a GoCommerce store: API token, verifier token, webhook URL, refunds, and what the module leaves out.
• Hyperswitch integration in Go Route payments through Hyperswitch, the open-source payments router, from a GoCommerce store: keys, payment links, webhook URL, refunds and limits.
• Lemon Squeezy integration in Go Sell through Lemon Squeezy as merchant of record from a GoCommerce store: the placeholder variant, four settings, webhook URL, refunds and limits.