canonical: https://jentic.com/apis/adyen.com/adyen-payment-webhooks-v1

# Adyen Payment webhooks (deprecated)

Adyen Balance Platform Payment Webhooks (v1) deliver legacy payment, incoming transfer, and outgoing transfer notifications for Adyen for Platforms balance platforms. The OpenAPI document defines the event payloads - balancePlatform.payment.created, payment.updated, incomingTransfer.created, incomingTransfer.updated, outgoingTransfer.created, and outgoingTransfer.updated - that Adyen POSTs to your endpoint. Adyen has deprecated this notification surface in favour of the accounting webhooks; use this spec only for receivers that have not yet migrated.

## For AI agents

Receive deprecated Adyen Balance Platform payment and transfer events for legacy receivers that have not migrated to accounting webhooks.

## Scope

Does not handle current accounting webhooks, configuration events, or report events - use for legacy v1 payment and transfer notification schemas only.

## Capabilities

- Parse balancePlatform.payment.created and payment.updated events for legacy payment notifications
- Handle balancePlatform.incomingTransfer.created and updated events for funds arriving in the platform
- Process balancePlatform.outgoingTransfer.created and updated events for funds leaving the platform
- Validate webhook delivery using HTTP basic auth credentials configured in the Adyen Customer Area
- Acknowledge events with a typed BalancePlatformNotificationResponse payload

## Use cases

### Maintain a Legacy Payment Webhook Receiver

Platforms that integrated with Adyen for Platforms before the accounting webhooks were released often still run a Payment webhook (v1) receiver. The OpenAPI document gives those receivers a typed schema for parsing balancePlatform.payment and balancePlatform.incomingTransfer/outgoingTransfer events, so legacy code can keep working while migration is planned.

Example prompt: Validate an incoming balancePlatform.payment.updated body against the PaymentNotificationRequest schema and dispatch it to the legacy receiver's payment-state service

### Migrate from Payment Webhooks to Accounting Webhooks

Adyen has deprecated this notification surface. Migrating to the accounting webhooks (transfer-webhooks) requires mapping each legacy event type to the new transfer event taxonomy and updating downstream consumers. The deprecated spec is the reference for what the legacy receiver currently expects, so a migration agent can compare schemas side by side.

Example prompt: Compare the PaymentNotificationRequest schema in this spec to TransferNotificationRequest in BalancePlatformTransferNotification-v3 and produce a field-by-field mapping for the migration plan

### Reconcile Legacy Incoming and Outgoing Transfers

Finance teams running a legacy receiver still rely on incomingTransfer and outgoingTransfer events to mark funds as arrived or sent. This spec is the source of truth for those event payloads - including counterparty data, amount, and status - so reconciliation jobs can match webhook events against ledger entries.

Example prompt: On a balancePlatform.incomingTransfer.created event, mark the corresponding ledger entry with status=funded using the transferId from the payload

### Agent-Assisted Migration Plan via Jentic

An agent owning the migration off this deprecated spec can use Jentic to load both the legacy and accounting webhook schemas, diff them, and generate the migration code. Jentic returns the typed schemas so the agent can reason about field-level mapping rather than scraping vendor docs.

Example prompt: Use Jentic to load both PaymentNotificationRequest and the TransferNotificationRequest from the v3 spec, then output a per-field mapping the migration code generator can consume

## Key resources

- **Payment events** — balancePlatform.payment.created and updated
- **Incoming transfer events** — balancePlatform.incomingTransfer.created and updated
- **Outgoing transfer events** — balancePlatform.outgoingTransfer.created and updated

## Why Jentic

- **Setup:** Wiring these deprecated Adyen Payment webhooks by hand means validating inbound calls with basic auth and parsing legacy v1 notification JSON against the right event type. Through Jentic you install once, import the Payment webhooks from the API Directory, store the basic auth credential once, and your agent validates payloads against typed schemas.
- **Permission scoping:** These are inbound event schemas rather than outbound calls with a resource id in the URL, so you limit the agent to the operations it needs, such as parsing an incoming transfer notification. Because you pick the operations, the agent only handles the legacy event types you include.
- **Credential handling:** The basic auth credential used to validate these webhook calls is stored once, encrypted, by your own Jentic One instance and injected at validation time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'parse an adyen incoming transfer webhook', and Jentic returns the matching event schema so the agent reasons about typed payloads rather than free-form JSON, without browsing the reference docs.

## Related APIs

- **Adyen Transfer webhooks** — The current accounting webhook surface that supersedes Payment webhooks v1
- **Adyen Configuration webhooks** — Sister webhook spec for account holder, balance account, and instrument changes
- **Adyen Balance Platform Configuration API** — The REST API used to read state that the webhooks notify you about

## FAQ

### Is the Adyen Payment webhooks API deprecated?

Yes. Adyen has deprecated this notification surface in favour of the accounting webhooks (the BalancePlatformTransferNotification family). New integrations should use the transfer webhooks; this spec exists for legacy receivers still in service.

### What authentication does the Payment webhooks use?

Adyen authenticates outbound webhook calls to your server using HTTP basic auth credentials configured in the Adyen Customer Area. Your endpoint must validate the username/password before trusting the payload. Through Jentic, those validation credentials are kept in your Jentic One instance.

### Which events does the Payment webhooks fire?

Six event types: balancePlatform.payment.created, payment.updated, incomingTransfer.created, incomingTransfer.updated, outgoingTransfer.created, and outgoingTransfer.updated. Each delivers a typed NotificationRequest payload defined in the spec.

### How do I migrate from Payment webhooks to Accounting webhooks?

Map each legacy event type to its accounting webhook equivalent in BalancePlatformTransferNotification-v3, update the receiver to parse TransferNotificationRequest, and dual-run for a period before switching off the legacy endpoint. Adyen documents the mapping in their migration guide.

### Should I build new integrations against this spec?

No. Build new integrations against the BalancePlatformTransferNotification-v3 spec instead. Use this spec only when maintaining or migrating an existing legacy receiver.

### Can I limit what my agent is allowed to do with the Adyen Payment Webhooks API?

Yes. Because Jentic One is self-hosted, you decide which of these inbound event schemas your agent may parse, so you can allow only the operations it needs, such as handling balancePlatform.incomingTransfer.created while excluding the payment or outgoingTransfer events. Since you pick the operations at import time, the agent only processes the legacy event types you include. The basic auth credential used to validate the webhook calls stays in your own Jentic One instance and is injected at validation time, so the agent never sees it.