The Adyen connector syncs merchant accounts from Adyen's Management API and ingests Adyen's webhook stream. It does not poll for payments or balances — Adyen's canonical transaction surface is the webhook feed, which the connector subscribes to at install time.
Prerequisites#
You need an Adyen Management API key with read access to MerchantAccount for the company. Webhooks use Basic Auth credentials (webhookUsername / webhookPassword) set on the webhook config in Adyen's Customer Area and sent as Authorization: Basic <base64(user:pass)> on every delivery.
Make sure to create an API key dedicated to Formance. Doing so will improve your auditability and security and will allow you to revoke access to Formance at any time if needed.
Installation#
curl -X POST $FORMANCE_API_URL/api/payments/v3/connectors/install/adyen \
-H "Content-Type: application/json" \
-d @config.jsonConfiguration fields#
| Field | Type | Required | Default |
|---|---|---|---|
apiKey | string | Yes | |
companyID | string | Yes | |
liveEndpointPrefix | string | No | |
pageSize | integer | No | 25 |
pollingPeriod | string | No | 30m |
webhookPassword | string | No | |
webhookUsername | string | No |
liveEndpointPrefix only applies in production — copy it from Adyen's Customer Area under Developers → API URLs (the company-specific fragment between https:// and -checkout-live.adyenpayments.com). Leave it empty for the test environment.
Capabilities#
FETCH_ACCOUNTS— merchant accounts viaGET /Management/v3/merchants.CREATE_WEBHOOKS— provisions a "Standard webhook" on the merchant at install, configured with the Basic Auth credentials from the config.TRANSLATE_WEBHOOKS— convertsAUTHORISATION,CAPTURE,REFUND,CHARGEBACK,CANCELLATION, etc. toPSPPayments.
Payments, balances, and external accounts are deliberately not polled — Adyen's canonical transaction surface is webhooks. Ensure the webhook is reachable (HTTPS, valid certificate) and the Basic Auth credentials match the config.
Account model#
Every Connectivity internal account is one Adyen merchant account from GET /Management/v3/merchants. The reference is the merchant ID; name is the display name; defaultAsset is null (Adyen merchants are multi-currency). No EXTERNAL accounts are emitted — Adyen "destination accounts" are not pulled (see Known gaps). See Accounts for the cross-connector model.
Asset model#
Currencies are uppercase ISO 4217 (USD, EUR, JPY), formatted to UMN at standard precision. Amounts are already in minor units — no scaling.
Status mapping#
Webhook events combine success: true|false with eventCode:
Adyen eventCode + success | Payment status |
|---|---|
AUTHORISATION + true | PENDING (until capture) |
CAPTURE + true, REFUND + true | SUCCEEDED |
AUTHORISATION + false, REFUND_FAILED, CHARGEBACK | FAILED |
CANCELLATION + true | CANCELLED |
Full event-code → type/status mapping in webhooks.go.
Metadata keys#
Under com.adyen.spec/:
- Account:
merchant_account_code,description,data_centers. - Payment:
event_code,psp_reference,merchant_reference,payment_method,payment_method_variant,acquirer_code.
Workflow tree#
FetchAccounts (periodic — merchant accounts only)
CreateWebhooks (one-shot at install)Known gaps#
- Balances and payouts are not exposed — Adyen's payout flow is bank-side, outside the Management API.
- External accounts (Adyen "destination accounts") are not pulled.
- Transfer / Payout Initiation is not implemented; outbound flows live in Adyen's Customer Area.