Helcim payments for GoCommerce

What it does

Configuration

Two settings are required: the API token and the webhook verifier token. 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 the webhookIn Helcim, point the webhook at https://your-api-host/api/checkout/helcim/webhook and copy its verifier token.
2. Install and configurePass helcim.New to gocommerce.New as below, or run the reference binary with -gateways and fill in Settings › Payment methods.
3. Load HelcimPay.jsOn the storefront, load Helcim’s script. POST /api/checkout/helcim answers with a client_action intent whose checkout_token opens the modal via appendHelcimPayIframe.
4. Let the webhook settle itWhen the shopper pays, Helcim’s cardTransaction webhook arrives, the module reads the transaction back, and the engine marks the order paid.

import (
	"os"

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

app, err := gocommerce.New(cfg,
	helcim.New(helcim.Config{
		APIToken:      os.Getenv("HELCIM_API_TOKEN"),
		VerifierToken: os.Getenv("HELCIM_VERIFIER_TOKEN"),
	}),
)

How it works

• Three signed headers

  webhook-id, webhook-timestamp and webhook-signature: an HMAC-SHA256 over the id, the timestamp and the body, keyed on the decoded verifier token. Any v1 signature may match during a rotation; a timestamp more than five minutes off is refused.

• The body proves nothing

  Helcim’s webhook is an id and a type, so the module fetches the transaction before deciding anything. If that read fails, the claim is released and the webhook answers 500 for Helcim to retry.

• Amount and currency must match

  A transaction whose amount or currency differs from the order it names is logged as an error and not settled — left for an operator who can see both sides.

• Only purchases settle

  Preauths, verifies and refunds coming back round are acknowledged and change nothing, as are transactions whose invoice number names no order here — a terminal sale, say.

• Each event once

  Claims are keyed on event type plus id in the module’s own table. A redelivery is answered 200 and changes nothing.

• Idempotent refunds

  A refund posts to Helcim against the transaction id the webhook recorded, with an idempotency key built from the order and the amount, so a retried refund is the same request. Anything but APPROVED is an error.

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.

• The storefront loads the scriptThere is no page to redirect to. A storefront that does not load HelcimPay.js cannot take a payment through this module.
• CAD and USDThe conversion assumes two decimal places, which the package says covers the currencies Helcim settles in.
• Mismatches wait for a personA transaction for a different amount or currency is acknowledged and not settled. The order stays unpaid until an operator looks.
• Refunds need the transactionThe refund goes against the transaction id the webhook recorded. An order without one has nothing to refund against, and the module says so.
• Dashboard refunds are not appliedA refund made in Helcim reaches the webhook as a non-purchase transaction and does not change the GoCommerce order.