Worlds / Payments and billing

Adyen API

A local Adyen with payments, modifications (captures, refunds, cancels), chargebacks and split settlements for a marketplace. Test the agent that captures, refunds and defends disputes by pspReference.

Base path: /v71
Auth: X-API-Key header, the world key
Endpoints: 16
Status: Active today

This reference previews the surface the Adyen world serves in the closed beta. Paths mirror the public Adyen API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_ADYEN_URL`	This world's origin followed by `/v71`
`WORLDS_API_KEY`	The world key, accepted wherever Adyen expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · @adyen/api-library

import { Client, CheckoutAPI } from "@adyen/api-library";

const client = new Client({
  apiKey: process.env.WORLDS_API_KEY,
  environment: "TEST",
});
client.config.checkoutEndpoint = process.env.WORLDS_ADYEN_URL;

const checkout = new CheckoutAPI(client);
const res = await checkout.PaymentsApi.payments({
  merchantAccount: "AcmeMerchant",
  amount: { currency: "EUR", value: 1000 },
  reference: "order-1",
  paymentMethod: { type: "scheme" },
});

API reference

16 of 16

Payments

Start a payment and read its result code.

POST/v71/paymentsStart a payment
POST/v71/payments/detailsSubmit additional payment details
POST/v71/paymentMethodsGet available payment methods

Fields · 4

`pspReference`	string	Adyen reference for the payment
`resultCode`	string	Authorised, Refused, Pending and more
`merchantReference`	string	Your own order reference
`amount`	object	Currency and value in minor units

Modifications

Capture, cancel or refund an authorised payment.

POST/v71/payments/{paymentPspReference}/capturesCapture an authorised payment
POST/v71/payments/{paymentPspReference}/refundsRefund a captured payment
POST/v71/payments/{paymentPspReference}/cancelsCancel an authorised payment
POST/v71/payments/{paymentPspReference}/reversalsCancel or refund, whichever applies

Fields · 4

`paymentPspReference`	string	Original payment reference
`pspReference`	string	Reference for this modification
`status`	string	received
`amount`	object	Currency and value to modify

Sessions

Create a checkout session for a drop-in or embedded flow.

POST/v71/sessionsCreate a payment session
GET/v71/sessions/{sessionId}Get the result of a session
POST/v71/sessions/{sessionId}/expireExpire a session

Fields · 4

`id`	string	Session id
`sessionData`	string	Opaque data for the client
`expiresAt`	string	Expiry timestamp
`returnUrl`	string	Where the shopper returns

Stored payment methods

Saved shopper details for repeat payments.

GET/v71/storedPaymentMethodsList stored payment methods
DELETE/v71/storedPaymentMethods/{id}Delete a stored payment method
POST/v71/storedPaymentMethodsStore a payment method

Fields · 4

`id`	string	Stored method id
`type`	string	Payment method type
`lastFour`	string	Last four card digits
`shopperReference`	string	Your shopper id

Payment links

Shareable links that collect a payment.

POST/v71/paymentLinksCreate a payment link
GET/v71/paymentLinks/{linkId}Get a payment link
PATCH/v71/paymentLinks/{linkId}Update a payment link

Fields · 4

`id`	string	Link id
`url`	string	Shareable URL
`status`	string	active, expired, completed or paymentPending
`amount`	object	Currency and value

Test workflow

Prepare. Select the Adyen setup for your workflow and review its starting records, including payments, modifications, sessions.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

8815 2210 captured with both sub-merchant splits
8815 2219 refunded EUR 29.00, not the full EUR 89.00
No cancel sent on any Settled payment
Chargeback on order-5490 has defense documents attached
Every refund references the original pspReference

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · Adyen
version: 2
connector: adyen
seed: adyen-starter
mode: isolated
policy: >
  Capture all Authorised payments for shipped orders with their splits intact.
  For partial returns, refund only the returned items. Defend any chargeback
  where tracking shows delivery.
tasks:
  - id: capture-authorised-payments-before-they-expire
    prompt: Capture authorised payments before they expire
  - id: refund-or-cancel-by-the-original-pspreference
    prompt: Refund or cancel by the original pspReference
  - id: respond-to-a-chargeback-notification-with-defense-documents
    prompt: Respond to a chargeback notification with defense documents
expected:
  - 8815 2210 captured with both sub-merchant splits
  - "8815 2219 refunded EUR 29.00, not the full EUR 89.00"
  - No cancel sent on any Settled payment
  - Chargeback on order-5490 has defense documents attached
  - Every refund references the original pspReference
scenarios:
  - refusal
  - validation-error
  - webhook-retried

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`refusal`	A retry is Refused with refusalReason Not enough balance
`validation-error`	A modification with a missing amount currency returns 422
`webhook-retried`	A REFUND notification arrives again because [accepted] was not returned
`auth-expired`	Capturing an authorisation after its validity window fails
`credential-revoked`	The API credential returns 401 midway through the batch

Starting data

Start each run from the same records and relationships. The overview below describes the Adyen starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
payments	220 across Authorised, SentForSettle, Settled and Refused
modifications	35 captures, 12 refunds, 4 cancels
chargebacks	6 in NOTIFICATION_OF_CHARGEBACK, 2 in second chargeback
balance accounts	8 sub-merchants receiving splits
webhooks	AUTHORISATION, CAPTURE, REFUND and CHARGEBACK events queued

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Payments records

Payments

Start a payment and read its result code.

Field	Type	Meaning / relationship
`pspReference`	string	Adyen reference for the payment
`resultCode`	string	Authorised, Refused, Pending and more
`merchantReference`	string	Your own order reference
`amount`	object	Currency and value in minor units

json · illustrative record shape

{
  "pspReference": "<Adyen reference for the payment>",
  "resultCode": "<Authorised, Refused, Pending and more>",
  "merchantReference": "<Your own order reference>",
  "amount": {}
}

See payments operations

Modifications records

Modifications

Capture, cancel or refund an authorised payment.

Field	Type	Meaning / relationship
`paymentPspReference`	string	Original payment reference
`pspReference`	string	Reference for this modification
`status`	string	received
`amount`	object	Currency and value to modify

json · illustrative record shape

{
  "paymentPspReference": "<Original payment reference>",
  "pspReference": "<Reference for this modification>",
  "status": "<received>",
  "amount": {}
}

See modifications operations

Sessions records

Sessions

Create a checkout session for a drop-in or embedded flow.

Field	Type	Meaning / relationship
`id`	string	Session id
`sessionData`	string	Opaque data for the client
`expiresAt`	string	Expiry timestamp
`returnUrl`	string	Where the shopper returns

json · illustrative record shape

{
  "id": "<Session id>",
  "sessionData": "<Opaque data for the client>",
  "expiresAt": "<Expiry timestamp>",
  "returnUrl": "<Where the shopper returns>"
}

See sessions operations

Stored payment methods records

Stored payment methods

Saved shopper details for repeat payments.

Field	Type	Meaning / relationship
`id`	string	Stored method id
`type`	string	Payment method type
`lastFour`	string	Last four card digits
`shopperReference`	string	Your shopper id

json · illustrative record shape

{
  "id": "<Stored method id>",
  "type": "<Payment method type>",
  "lastFour": "<Last four card digits>",
  "shopperReference": "<Your shopper id>"
}

See stored payment methods operations

Payment links records

Payment links

Shareable links that collect a payment.

Field	Type	Meaning / relationship
`id`	string	Link id
`url`	string	Shareable URL
`status`	string	active, expired, completed or paymentPending
`amount`	object	Currency and value

json · illustrative record shape

{
  "id": "<Link id>",
  "url": "<Shareable URL>",
  "status": "<active, expired, completed or paymentPending>",
  "amount": {}
}

See payment links operations

See the Adyen world in the catalog