paybondpaybond
Sign in

Integration · Adyen

Configure Adyen settlement

Tenant-admin guide: save BYO Adyen Checkout credentials, enable adyen_manual_capture, and wire HMAC webhooks for async capture and cancel finality.

  • BYO merchant
  • HMAC webhook
  • adyen_manual_capture
  1. 01Connect
  2. 02Configure
  3. 03Verify
  4. 04Go live

In short: this connects your own Adyen account so Paybond can hold and release funds on it. Before production intents can settle against Adyen, a tenant admin configures Checkout credentials and the adyen_manual_capture rail. Paybond resolves merchant account, API keys, and HMAC secrets server-side from this configuration — agents and SDK clients never supply Adyen credentials.

This guide covers operator setup for Adyen, analogous to Configure settlement rails and Configure Shopify settlement.

Console workspace

Open Configuration → Settlement (/console/configuration/settlement) as a tenant admin.

From here you should be able to:

  • Save an Adyen Checkout destination (merchant account, optional store, test/live environment)
  • Enter write-only API key and webhook HMAC secret (never redisplayed after save)
  • Confirm readiness (API key ready / HMAC ready / stored payment method ready / environment badges)
  • Enable the adyen_manual_capture rail when prerequisites are satisfied

Supported Adyen rail

RailWhat it settlesRequirement
adyen_manual_captureCheckout payment with manualCapture; Harbor captures or cancels after evidence evaluationActive Adyen destination with webhook HMAC for CAPTURE / CANCELLATION finality

Step 1 — Create Checkout credentials in Adyen

In the Adyen Customer Area for your company:

  1. Create or select a merchant account (test first).
  2. Generate a Checkout API key (X-API-Key) for server-to-server payments.
  3. For live, note the company live URL prefix used by Checkout live hosts.
  4. Create a standard webhook and copy the HMAC key (hex).

Register Paybond webhook URLs (ports 443 / 8443 / 8843 as required by Adyen):

  • Live: https://api.paybond.ai/webhooks/live/adyen (or /webhooks/adyen)
  • Sandbox tenant test traffic: https://api.paybond.ai/webhooks/sandbox/adyen

Enable at least AUTHORISATION, CAPTURE, CAPTURE_FAILED, and CANCELLATION. Also enable CHARGEBACK when you want bound chargebacks to freeze disputable intents (see Chargebacks below). REFUND remains optional for observation.

Step 2 — Save the destination in Console

In Configuration → Settlement:

  1. Enter merchant account (and optional store).
  2. Choose test or live environment. Sandbox tenants are restricted to test.
  3. For live, enter the company live URL prefix.
  4. Paste the API key, HMAC secret, and (for live funding) a stored payment method id or paymentMethod JSON, then save.

Secrets and the stored payment method are write-only. After save, the console shows masked merchant details and ready badges only — not decrypted keys or PM ids.

HMAC verification

A destination HMAC secret is required for live webhook ingest — not optional. Paybond verifies Adyen notification signatures against the secret you vaulted in Console Settlement and rejects live webhooks with a missing or invalid HMAC.

After you rotate the HMAC key in Adyen Customer Area, re-save the destination secret in Console Settlement immediately so verification stays aligned.

CLI readiness (paybond adyen)

After paybond login, use the Kit CLI to read settlement-config readiness (no secret upsert via CLI):

Terminal
Terminal commandSwipe to inspect long lines
paybond adyen ready
paybond adyen doctor
paybond adyen doctor --format json
  • adyen ready checks adyen_manual_capture in allowed_rails, destination present, API key and HMAC configured, vaulted stored payment method, live URL prefix when live, and surfaces the paid-plan gate message when live destinations are blocked.
  • adyen doctor expands ready with expected webhook URLs (/webhooks/live/adyen and /webhooks/sandbox/adyen), sandbox/live mismatch hints against the signed-in principal, and a pointer to Console destination upsert.
  • Never pass --live-prefix, --api-key, --hmac-secret, --merchant-account, or --environment on paybond adyen argv (rejected; visible in process listings). Upsert those in Console → Settlement write-only fields.

Step 3 — Enable adyen_manual_capture

Once readiness reports an active destination:

  1. Enable Adyen manual capture in allowed rails.
  2. Optionally set it as the default rail.
  3. Save routing.

Harbor rejects creates on this rail when no active Adyen destination exists for the tenant.

Step 4 — Async terminal settlement

Unlike Stripe Connect capture on HTTP success alone, Adyen capture and cancel are asynchronous:

  1. Evidence evaluation moves the intent to evidence_submitted.
  2. Settlement confirm requests Adyen capture or cancel and waits for confirmation.
  3. The intent stays in evidence_submitted until Paybond receives successful CAPTURE / CANCELLATION webhooks and finalizes to released / refunded.

Stuck pending modifications

When capture or cancel webhooks lag, Paybond reconciles pending modifications against Adyen. Cases that still need an operator appear under Settlements → Exceptions in the console (same queue as Stripe and Shopify rails).

Chargebacks

When an Adyen CHARGEBACK webhook can be matched to a tenant intent (and its prior authorization), Paybond freezes automated settlement for that intent while it is still in funded or evidence_submitted. An operator then resolves the case through the dispute workflow.

If the webhook cannot be matched (for example the authorization payment reference was never stored), Paybond does not auto-freeze — it stays an observation signal for manual review. Stripe chargeback webhooks work the same way: observation only, never an automatic dispute. Details: Disputes and evidence evaluation.

Where to go next

Configure settlement rails →

Settlement with payment providers →

Fund intents by rail →