Adyen payments for GoCommerce

What it does

Configuration

Four settings are required: the API key, the merchant account, the webhook’s HMAC key and the Checkout API endpoint. 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. Set up the webhookIn Adyen’s Customer Area, point a webhook at https://your-api-host/api/checkout/adyen/webhook and generate its HMAC key.
2. Choose the endpointTest is https://checkout-test.adyen.com/v71. Live is your own prefixed host, https://{prefix}-checkout-live.adyenpayments.com/checkout/v71 — the module will not guess it.
3. Install and configurePass adyen.New to gocommerce.New as below, or run the reference binary with -gateways and fill in all four settings under Settings › Payment methods.
4. Take a paymentPOST /api/checkout/adyen answers with a redirect intent whose url is the payment link. The AUTHORISATION notification marks the order paid.

import (
	"os"

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

app, err := gocommerce.New(cfg,
	adyen.New(adyen.Config{
		APIKey:          os.Getenv("ADYEN_API_KEY"),
		MerchantAccount: os.Getenv("ADYEN_MERCHANT_ACCOUNT"),
		HMACKey:         os.Getenv("ADYEN_HMAC_KEY"),
		BaseURL:         "https://checkout-test.adyen.com/v71",
	}),
)

How it works

• Payment links, not Drop-in

  Checkout creates a link with POST /paymentLinks: the amount in minor units, the order number as reference, and the shopper’s email and two-letter country when the order has them. The storefront only redirects.

• Every item verified first

  Adyen signs eight fields of each notification item — PSP reference, original reference, merchant account, merchant reference, amount, currency, event code and success — with the HMAC in additionalData. One forged item rejects the whole batch.

• Only signed fields pick the order

  The order is found from merchantReference, which the HMAC covers, not from the metadata Adyen echoes back, which it does not. A valid signature for one payment cannot settle somebody else’s order.

• Each event once

  Claims are keyed on event code plus PSP reference in the module’s own table, so a retry is a duplicate and two different events about one payment stay distinct. The handler answers [accepted], which is what stops Adyen retrying.

• A failed update is retried

  If the engine cannot apply a notification, the claim is released and the webhook answers 500, so Adyen’s retry finds work to do.

• Refunds by PSP reference

  A refund posts to Adyen against the PSP reference the AUTHORISATION recorded, for the amount asked, and keeps the reference Adyen returns. A later REFUND notification that failed is logged as an error for an operator to reconcile.

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.

• No default endpointUntil BaseURL is set, the module does not count as configured. The package chose that over a test default that would turn a misconfigured live store into one taking pretend money.
• Redirect onlyNo Drop-in or Components. A store that wants Adyen’s in-page checkout builds it on its storefront; this module only creates payment links.
• Paid on authorisationA successful AUTHORISATION marks the order paid. The module sends no capture and reads no CAPTURE event; if your account captures manually, that happens in Adyen.
• Refunds wait for the notificationThe refund is issued against the PSP reference the AUTHORISATION notification wrote. Before that arrives, the order has nothing to refund against.
• Chargebacks are only loggedCHARGEBACK, NOTIFICATION_OF_CHARGEBACK and SECOND_CHARGEBACK are logged as warnings. The engine has no chargeback state, so the order does not change.
• Failed refunds are not undoneA REFUND notification with success=false, after the engine recorded the refund, is logged and nothing more. The two sets of books need a person to reconcile them.