### Example x-groups Extension

Source: https://github.com/adyen/adyen-openapi/blob/main/README.md

This extension provides a list of all endpoint groups for the selected API.

```yaml
x-groups:
  - General
  - Modifications
```

--------------------------------

### Example x-groupName and x-sortIndex Extensions

Source: https://github.com/adyen/adyen-openapi/blob/main/README.md

These extensions specify how to group endpoints and sort them within a group.

```yaml
paths:
    ...
    post:
      ...
      x-groupName: Modifications
      x-sortIndex: 5
   ...
```

--------------------------------

### Generate Client SDK with openapi-generator-cli

Source: https://context7.com/adyen/adyen-openapi/llms.txt

Use the `openapi-generator-cli` tool to generate a client SDK for your chosen language. This example shows generating a TypeScript Axios client for the CheckoutService v72.

```bash
# --- Option 3: openapi-generator-cli (generate a client SDK) ---
# Install: npm install @openapitools/openapi-generator-cli -g

openapi-generator-cli generate \
  -i json/CheckoutService-v72.json \
  -g typescript-axios \
  -o ./generated/checkout-v72 \
  --additional-properties=npmName=adyen-checkout-client,npmVersion=72.0.0
```

--------------------------------

### Get Store Details

Source: https://github.com/adyen/adyen-openapi/wiki/Management-API-v1-‐--v3

Retrieves the details of a specific store, including its phone number.

```APIDOC
## GET /stores/{storeId}

### Description
Retrieves the details of a specific store, including its phone number.

### Method
GET

### Endpoint
/stores/{storeId}

### Response
#### Success Response (200)
- **phoneNumber** (object) - The phone number of the store, including '+' and country code in the [E.164](https://en.wikipedia.org/wiki/E.164) format. If passed in a different format, we convert and validate the phone number against E.164.
```

--------------------------------

### Get BIN Lookup Cost Estimate (v54)

Source: https://context7.com/adyen/adyen-openapi/llms.txt

Use this endpoint to estimate interchange costs and processing fees for a given card BIN and transaction amount. It's useful for dynamic surcharging and cost-estimation flows.

```bash
# Base URL: https://pal-test.adyen.com/pal/servlet/BinLookup/v54

curl -X POST "https://pal-test.adyen.com/pal/servlet/BinLookup/v54/getCostEstimate" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{ 
    "amount": { "currency": "EUR", "value": 5000 }, 
    "assumptions": { 
      "assumeLevel3Data": true, 
      "assume3DSecureAuthenticated": true 
    }, 
    "cardNumber": "411111111111", 
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT", 
    "merchantDetails": { "countryCode": "NL", "enrolledIn3DSecure": true, "mcc": "7411" }, 
    "shopperInteraction": "Ecommerce" 
  }'
```

--------------------------------

### Example Deprecation Extensions

Source: https://github.com/adyen/adyen-openapi/blob/main/README.md

These extensions help add information when an endpoint or field has been added or deprecated. `x-deprecatedMessage` provides a human-readable message explaining what to use instead.

```yaml
        recurringDetailReference:
          deprecated: true
          x-deprecatedInVersion: 49
          x-deprecatedMessage: Use `storedPaymentMethodId` instead.
          description: This is the `recurringDetailReference` returned in the response when you created the token.
          type: string
        storedPaymentMethodId:
          x-addedInVersion: 49
          description: This is the `recurringDetailReference` returned in the response when you created the token.
          type: string
```

--------------------------------

### GET /companies/{companyId}/webhooks/{webhookId}

Source: https://github.com/adyen/adyen-openapi/wiki/Management-API-v1-‐--v3

Retrieve details of a specific webhook configuration for a company, including encryption protocol settings.

```APIDOC
## GET /companies/{companyId}/webhooks/{webhookId}

### Description
Retrieve details of a specific webhook.

### Method
GET

### Endpoint
/companies/{companyId}/webhooks/{webhookId}

### Response
#### Success Response (200)
OK - the request has succeeded.

* Changed content type : `application/json`

    * Added property `encryptionProtocol` (object) - SSL version to access the public webhook URL. Possible values: TLSv1.3, TLSv1.2, HTTP (Test environment only). Defaults to TLSv1.2 if not specified.
    * Deleted property `sslVersion` (object) - SSL version to access the public webhook URL. Possible values: TLSv1.3, TLSv1.2, HTTP (Test environment only). Defaults to TLSv1.2 if not specified.
```

--------------------------------

### Stored Payment Methods (GET / DELETE)

Source: https://context7.com/adyen/adyen-openapi/llms.txt

Lists all stored payment methods (tokens) for a shopper, and deletes a specific stored method. Used to manage one-click / recurring payment tokens on behalf of a shopper.

```APIDOC
## Stored Payment Methods (v72)

### Description
Lists all stored payment methods (tokens) for a shopper, and deletes a specific stored method. Used to manage one-click / recurring payment tokens on behalf of a shopper.

### List Stored Payment Methods

#### Method
GET

#### Endpoint
/v72/storedPaymentMethods

#### Query Parameters
- **shopperReference** (string) - Required - Your reference to uniquely identify a shopper.
- **merchantAccount** (string) - Required - Your Adyen merchant account.

#### Response
##### Success Response (200)
- **storedPaymentMethods** (array) - A list of stored payment methods.
  - **id** (string) - The unique identifier of the stored payment method.
  - **type** (string) - The type of the payment method (e.g., "scheme").
  - **brand** (string) - The brand of the card (e.g., "visa").
  - **lastFour** (string) - The last four digits of the card number.
  - **expiryMonth** (string) - The expiry month of the card.
  - **expiryYear** (string) - The expiry year of the card.
  - **name** (string) - The cardholder's name.
  - **supportedShopperInteractions** (array) - A list of shopper interactions supported by this stored payment method.

##### Response Example
```json
{
  "storedPaymentMethods": [
    {
      "id": "8315232733762535",
      "type": "scheme",
      "brand": "visa",
      "lastFour": "1111",
      "expiryMonth": "03",
      "expiryYear": "2030",
      "name": "VISA",
      "supportedShopperInteractions": ["Ecommerce","ContAuth"]
    }
  ]
}
```

### Delete a Stored Payment Method

#### Method
DELETE

#### Endpoint
/v72/storedPaymentMethods/{id}

#### Parameters
##### Path Parameters
- **id** (string) - Required - The unique identifier of the stored payment method to delete.

##### Query Parameters
- **shopperReference** (string) - Required - Your reference to uniquely identify a shopper.
- **merchantAccount** (string) - Required - Your Adyen merchant account.

#### Response
##### Success Response (204)
No Content on success.
```

--------------------------------

### Management API — GET /merchants and GET /merchants/{merchantId} (v3)

Source: https://context7.com/adyen/adyen-openapi/llms.txt

Lists all merchant accounts accessible to the authenticated API credential, or retrieves details for a specific merchant. Used to discover account structure for multi-merchant integrations.

```APIDOC
## GET /merchants and GET /merchants/{merchantId}

### Description
Lists all merchant accounts accessible to the authenticated API credential, or retrieves details for a specific merchant. Used to discover account structure for multi-merchant integrations.

### Method
GET

### Endpoint
/merchants
/merchants/{merchantId}

### Parameters
#### Query Parameters
- **pageSize** (integer) - Optional - Number of records to return.
- **pageNumber** (integer) - Optional - The page number to retrieve.

#### Path Parameters
- **merchantId** (string) - Required - The unique identifier of the merchant.

### Request Example
```bash
# List merchants
curl "https://management-test.adyen.com/v3/merchants?pageSize=10&pageNumber=1" \
  -H "X-API-Key: YOUR_API_KEY"

# Get a specific merchant
curl "https://management-test.adyen.com/v3/merchants/MID1234567" \
  -H "X-API-Key: YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **itemsTotal** (integer) - Total number of merchants.
- **pagesTotal** (integer) - Total number of pages.
- **data** (array) - Array of merchant objects.
  - **id** (string) - Merchant ID.
  - **companyId** (string) - Company ID.
  - **status** (string) - Merchant status.
  - **merchantCity** (string) - City of the merchant.

#### Response Example
```json
{
  "itemsTotal": 2,
  "pagesTotal": 1,
  "data": [
    { "id": "MID1234567", "companyId": "CID123", "status": "Active", "merchantCity": "Amsterdam" },
    { "id": "MID7654321", "companyId": "CID123", "status": "Active", "merchantCity": "London" }
  ]
}
```
```

--------------------------------

### Generate Onboarding Link (Legal Entity Service v4)

Source: https://context7.com/adyen/adyen-openapi/llms.txt

Generate a hosted onboarding URL for a legal entity to upload KYC documents and complete verification. This is used to embed Adyen's onboarding UI within a marketplace platform.

```bash
curl -X POST "https://kyc-test.adyen.com/lem/v4/legalEntities/LE3227C223222C5GXQXF68M5/onboardingLinks" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "locale": "en-US",
    "redirectUrl": "https://your-platform.com/onboarding/complete",
    "themeId": "YOUR_THEME_ID",
    "settings": {
      "editPrefilledCountry": false,
      "allowInpageRedirect": false
    }
  }'
```

--------------------------------

### Initiate Payout (Payout API v68)

Source: https://context7.com/adyen/adyen-openapi/llms.txt

Issues an immediate payout to a shopper's stored payment instrument. Requires payout-enabled credentials and a valid merchant account.

```bash
curl -X POST "https://pal-test.adyen.com/pal/servlet/Payout/v68/payout" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_PAYOUT_API_KEY" \
  -d '{
    "amount": { "currency": "EUR", "value": 3000 },
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "reference": "payout-001",
    "shopperReference": "shopper-123",
    "card": {
      "number": "4111111111111111",
      "expiryMonth": "03",
      "expiryYear": "2030",
      "holderName": "John Smith"
    }
  }'
```

--------------------------------

### Legal Entity Service — POST /legalEntities/{id}/onboardingLinks (v4)

Source: https://context7.com/adyen/adyen-openapi/llms.txt

Generates a hosted onboarding URL where the legal entity can upload KYC documents and complete verification steps. Used to embed Adyen's onboarding UI within a marketplace platform flow.

```APIDOC
## POST /legalEntities/{id}/onboardingLinks

### Description
Generates a hosted onboarding URL where the legal entity can upload KYC documents and complete verification steps. Used to embed Adyen's onboarding UI within a marketplace platform flow.

### Method
POST

### Endpoint
/legalEntities/{id}/onboardingLinks

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the legal entity.

#### Request Body
- **locale** (string) - Optional - The locale for the onboarding page (e.g., "en-US").
- **redirectUrl** (string) - Required - The URL to redirect to after onboarding is complete.
- **themeId** (string) - Optional - The ID of the theme to use for the onboarding page.
- **settings** (object) - Optional - Settings for the onboarding flow.
  - **editPrefilledCountry** (boolean) - Optional - Whether to allow editing the prefilled country.
  - **allowInpageRedirect** (boolean) - Optional - Whether to allow in-page redirects.

### Request Example
```bash
curl -X POST "https://kyc-test.adyen.com/lem/v4/legalEntities/LE3227C223222C5GXQXF68M5/onboardingLinks" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d 
    "locale": "en-US",
    "redirectUrl": "https://your-platform.com/onboarding/complete",
    "themeId": "YOUR_THEME_ID",
    "settings": {
      "editPrefilledCountry": false,
      "allowInpageRedirect": false
    }
  }'
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the onboarding link.
- **url** (string) - The generated hosted onboarding URL.

#### Response Example
```json
{
  "id": "OL0000000000000001",
  "url": "https://your-company.adyen.com/onboarding?token=eyJ..."
}
```
```

--------------------------------

### Create Legal Entity (Legal Entity Service v4)

Source: https://context7.com/adyen/adyen-openapi/llms.txt

Create a legal entity (individual, organization, or sole proprietorship) for onboarding platforms and marketplace sub-merchants. This is a prerequisite for the KYC verification flow.

```bash
# Base URL: https://kyc-test.adyen.com/lem/v4

curl -X POST "https://kyc-test.adyen.com/lem/v4/legalEntities" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "type": "individual",
    "individual": {
      "name": { "firstName": "Jane", "lastName": "Doe" },
      "birthData": { "dateOfBirth": "1990-05-15" },
      "residentialAddress": {
        "country": "NL",
        "street": "Simon Carmiggeltstraat",
        "houseNumberOrName": "6-50",
        "city": "Amsterdam",
        "postalCode": "1011 DJ"
      },
      "email": "jane.doe@example.com",
      "phone": { "number": "+31612345678", "type": "mobile" }
    },
    "reference": "legal-entity-ref-001"
  }'
```

--------------------------------

### GET /paymentLinks/{linkId}

Source: https://github.com/adyen/adyen-openapi/wiki/Checkout-API-Migration-v70-‐--v71

Retrieves a specific payment link by its ID. Includes details about the expiration date.

```APIDOC
## GET /paymentLinks/{linkId}

### Description
Retrieves a specific payment link by its ID. Includes details about the expiration date.

### Method
GET

### Endpoint
/paymentLinks/{linkId}

### Response
#### Success Response (200)
- **expiresAt** (object) - The date when the payment link expires.
```

--------------------------------

### Create a Balance Account using cURL

Source: https://context7.com/adyen/adyen-openapi/llms.txt

Create a new balance account associated with an account holder. This account will hold funds and can support multiple currencies.

```bash
curl -X POST "https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "accountHolderId": "AH3227C223222C5GXQXF68M5",
    "description": "Main EUR account",
    "reference": "balance-acct-001",
    "defaultCurrencyCode": "EUR",
    "metadata": { "internalId": "user-001" }
  }'
```

--------------------------------

### GET /grants/{id}

Source: https://github.com/adyen/adyen-openapi/wiki/Transfers-API-v3-‐--v4

Retrieves a specific grant by its ID. The documentation for this endpoint is incomplete in the provided text.

```APIDOC
## GET /grants/{id}

### Description
Retrieves a specific grant by its ID.

### Method
GET

### Endpoint
/grants/{id}
```

--------------------------------

### GET /grants

Source: https://github.com/adyen/adyen-openapi/wiki/Transfers-API-v3-‐--v4

Retrieves a list of grants. This endpoint can return various error codes indicating issues with the request or server.

```APIDOC
## GET /grants

### Description
Retrieves a list of grants.

### Method
GET

### Endpoint
/grants

### Response
#### Success Response (200)
- **response** (object) - JSON response payload.

#### Error Responses
- **400 Bad Request** - A problem reading or understanding the request.
- **401 Unauthorized** - Authentication required.
- **403 Forbidden** - Insufficient permissions to process the request.
- **404 Not Found** - The payment was not found.
- **422 Unprocessable Entity** - A request validation error.
- **500 Internal Server Error** - The server could not process the request.
```

--------------------------------

### GET /transactions/{id}

Source: https://github.com/adyen/adyen-openapi/wiki/Transfers-API-v3-‐--v4

Retrieves details of a specific transaction. This endpoint has seen changes in its parameters and response structure between API versions.

```APIDOC
## GET /transactions/{id}

### Description
Retrieves the details of a specific transaction using its unique identifier.

### Method
GET

### Endpoint
/transactions/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Unique identifier of the transaction.

### Response
#### Success Response (200 OK)
- **accountHolder** (object) - Required - Information about the account holder.
    - **description** (object) - The description of the resource.
    - **id** (object) - The unique identifier of the resource.
    - **reference** (object) - The reference for the resource.
- **balanceAccount** (object) - Required - Information about the balance account.
- **transfer** (object) - Information about the transfer.
    - **id** (object) - The ID of the resource.
    - **reference** (object) - The reference from the /transfers request. If not provided, Adyen generates a unique reference.
- **accountHolderId** (string) - Optional - Unique identifier of the account holder.
- **balanceAccountId** (string) - Optional - Unique identifier of the balance account.
- **counterparty** (object) - Optional - Information about the counterparty.
- **createdAt** (string) - Optional - The date the transaction was created.
- **reference** (string) - Optional - The reference from the /transfers request. If not provided, Adyen generates a unique reference.

#### Error Responses
- **401 Unauthorized** - Unauthorized - authentication required.
- **403 Forbidden** - Forbidden - insufficient permissions to process the request.
- **422 Unprocessable Entity** - Unprocessable Entity - a request validation error.
- **500 Internal Server Error** - Internal Server Error - the server could not process the request.

### Response Example (200 OK)
```json
{
  "accountHolder": {
    "description": "...",
    "id": "...",
    "reference": "..."
  },
  "balanceAccount": {},
  "transfer": {
    "id": "...",
    "reference": "..."
  },
  "accountHolderId": "...",
  "balanceAccountId": "...",
  "counterparty": {},
  "createdAt": "...",
  "reference": "..."
}
```
```

--------------------------------

### Loading OpenAPI Definitions

Source: https://context7.com/adyen/adyen-openapi/llms.txt

Instructions on how to load Adyen's OpenAPI definition files into various tools for integration and development.

```APIDOC
## Loading OpenAPI Definitions

All definition files are ready to use directly with standard OpenAPI tooling. Below are the most common integration patterns.

### Option 1: Swagger Editor (web)
Upload the file at https://editor.swagger.io/ or load by URL:
`https://raw.githubusercontent.com/Adyen/adyen-openapi/main/json/CheckoutService-v72.json`

### Option 2: Postman import
Import via Postman UI: File > Import > Link
URL: `https://raw.githubusercontent.com/Adyen/adyen-openapi/main/json/CheckoutService-v72.json`

### Option 3: openapi-generator-cli (generate a client SDK)
Install: `npm install @openapitools/openapi-generator-cli -g`

```bash
openapi-generator-cli generate \
  -i json/CheckoutService-v72.json \
  -g typescript-axios \
  -o ./generated/checkout-v72 \
  --additional-properties=npmName=adyen-checkout-client,npmVersion=72.0.0
```

### Option 4: Validate with spectral
`npm install -g @stoplight/spectral-cli`

`spectral lint json/CheckoutService-v72.json`

### Option 5: Serve locally with swagger-ui-express (Node.js)
`npm install swagger-ui-express`

```javascript
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const checkoutSpec = require('./json/CheckoutService-v72.json');

const app = express();
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(checkoutSpec));
app.listen(3000, () => console.log('Docs at http://localhost:3000/api-docs'));
```
```

--------------------------------

### Initiate Online Payment - Checkout API

Source: https://context7.com/adyen/adyen-openapi/llms.txt

Use this endpoint to initiate online payments. It supports various payment methods including cards, wallets, and local options. Ensure you replace placeholders with your actual API key, merchant account, and order details.

```bash
curl -X POST "https://checkout-test.adyen.com/v72/payments" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "amount": {
      "currency": "EUR",
      "value": 1000
    },
    "reference": "YOUR_ORDER_NUMBER",
    "paymentMethod": {
      "type": "scheme",
      "encryptedCardNumber": "test_4111111111111111",
      "encryptedExpiryMonth": "test_03",
      "encryptedExpiryYear": "test_2030",
      "encryptedSecurityCode": "test_737"
    },
    "returnUrl": "https://your-company.com/checkout?shopperOrder=12xy",
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT"
  }'
```

--------------------------------

### GET /transactions

Source: https://github.com/adyen/adyen-openapi/wiki/Transfers-API-v3-‐--v4

Retrieves transaction information. Supports various error responses including Unauthorized, Forbidden, Unprocessable Entity, and Internal Server Error.

```APIDOC
## GET /transactions

### Description
Retrieves transaction information.

### Method
GET

### Endpoint
/transactions

### Response
#### Success Response (200)
- **response** (object) - JSON response payload.

#### Error Responses
- **401 Unauthorized** - Unauthorized - authentication required.
- **403 Forbidden** - Forbidden - insufficient permissions to process the request.
- **422 Unprocessable Entity** - Unprocessable Entity - a request validation error.
- **500 Internal Server Error** - Internal Server Error - the server could not process the request.
```

--------------------------------

### Create API Credential (Management API v3)

Source: https://context7.com/adyen/adyen-openapi/llms.txt

Create a new API credential for a company account, which includes an API key and basic auth user. Credentials can be restricted by roles and allowed origins.

```bash
curl -X POST "https://management-test.adyen.com/v3/companies/CID123/apiCredentials" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_ADMIN_API_KEY" \
  -d '{
    "description": "Checkout integration credential",
    "allowedOrigins": ["https://your-company.com"],
    "roles": ["Merchant PAL Webservice role", "Checkout webservice role"]
  }'
```

--------------------------------

### Create Store

Source: https://github.com/adyen/adyen-openapi/wiki/Management-API-v1-‐--v3

Creates a new store with the provided details, including phone number validation.

```APIDOC
## POST /stores

### Description
Creates a new store with the provided details, including phone number validation.

### Method
POST

### Endpoint
/stores

### Parameters
#### Request Body
- **phoneNumber** (object) - Optional - The phone number of the store, including '+' and country code in the [E.164](https://en.wikipedia.org/wiki/E.164) format. If passed in a different format, we convert and validate the phone number against E.164.

### Response
#### Success Response (200)
- **phoneNumber** (object) - The phone number of the store, including '+' and country code in the [E.164](https://en.wikipedia.org/wiki/E.164) format. If passed in a different format, we convert and validate the phone number against E.164.
```

--------------------------------

### Create a Transfer using cURL

Source: https://context7.com/adyen/adyen-openapi/llms.txt

Use this endpoint to initiate a transfer between balance accounts. Ensure you have the correct balance account IDs and API key.

```bash
curl -X POST "https://balanceplatform-api-test.adyen.com/btl/v4/transfers" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "amount": { "currency": "EUR", "value": 10000 },
    "balanceAccountId": "BAB8B2C3D4E5F6G7H8",
    "category": "bank",
    "counterparty": {
      "bankAccount": {
        "accountHolder": { "type": "individual", "fullName": "Jane Doe" },
        "accountIdentification": {
          "type": "iban",
          "iban": "NL91ABNA0417164300"
        }
      }
    },
    "priority": "regular",
    "reference": "transfer-ref-001",
    "referenceForBeneficiary": "Invoice 12345"
  }'
```

--------------------------------

### Get Specific Merchant Details (Management API v3)

Source: https://context7.com/adyen/adyen-openapi/llms.txt

Retrieve detailed information for a specific merchant account using its unique ID. This is useful for multi-merchant integrations to discover account structures.

```bash
# Get a specific merchant
curl "https://management-test.adyen.com/v3/merchants/MID1234567" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------

### Serve OpenAPI Docs Locally with swagger-ui-express

Source: https://context7.com/adyen/adyen-openapi/llms.txt

Integrate Adyen's OpenAPI specification into a Node.js application using `swagger-ui-express` to serve interactive API documentation locally. This allows for easy viewing and testing of API endpoints.

```javascript
# --- Option 5: Serve locally with swagger-ui-express (Node.js) ---
# npm install swagger-ui-express

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const checkoutSpec = require('./json/CheckoutService-v72.json');

const app = express();
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(checkoutSpec));
app.listen(3000, () => console.log('Docs at http://localhost:3000/api-docs'));
```

--------------------------------

### Create Webhook Subscription (Management API v3)

Source: https://context7.com/adyen/adyen-openapi/llms.txt

Create a webhook subscription for a merchant to receive asynchronous payment event notifications. Supports HTTPS with HMAC signing and TLS 1.2/1.3.

```bash
curl -X POST "https://management-test.adyen.com/v3/merchants/MID1234567/webhooks" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "type": "standard",
    "url": "https://your-server.com/adyen/webhook",
    "username": "YOUR_WEBHOOK_USERNAME",
    "password": "YOUR_WEBHOOK_PASSWORD",
    "active": true,
    "communicationFormat": "json",
    "encryptionProtocol": "TLSv1.2",
    "acceptsExpiredCertificate": false,
    "acceptsSelfSignedCertificate": false,
    "acceptsUntrustedRootCertificate": false
  }'
```

--------------------------------

### BIN Lookup Service - Get Cost Estimate

Source: https://context7.com/adyen/adyen-openapi/llms.txt

Returns an estimated interchange cost and processing fee for a given card BIN and transaction amount. Used for dynamic surcharging and cost-estimation flows at checkout.

```APIDOC
## POST /getCostEstimate (v54)

### Description
Returns an estimated interchange cost and processing fee for a given card BIN and transaction amount. Used for dynamic surcharging and cost-estimation flows at checkout.

### Method
POST

### Endpoint
https://pal-test.adyen.com/pal/servlet/BinLookup/v54/getCostEstimate

### Request Body
- **amount** (object) - Required - The transaction amount.
  - **currency** (string) - Required - Currency code.
  - **value** (integer) - Required - Amount value.
- **assumptions** (object) - Optional - Assumptions for the cost estimation.
  - **assumeLevel3Data** (boolean) - Optional - Whether to assume Level 3 data is available.
  - **assume3DSecureAuthenticated** (boolean) - Optional - Whether to assume 3D Secure authentication.
- **cardNumber** (string) - Required - The card number (BIN).
- **merchantAccount** (string) - Required - Your Adyen merchant account.
- **merchantDetails** (object) - Optional - Details about the merchant.
  - **countryCode** (string) - Optional - Country code of the merchant.
  - **enrolledIn3DSecure** (boolean) - Optional - Whether the merchant is enrolled in 3D Secure.
  - **mcc** (string) - Optional - Merchant category code.
- **shopperInteraction** (string) - Optional - The shopper interaction type (e.g., "Ecommerce").

### Request Example
```json
{
  "amount": { "currency": "EUR", "value": 5000 },
  "assumptions": {
    "assumeLevel3Data": true,
    "assume3DSecureAuthenticated": true
  },
  "cardNumber": "411111111111",
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "merchantDetails": { "countryCode": "NL", "enrolledIn3DSecure": true, "mcc": "7411" },
  "shopperInteraction": "Ecommerce"
}
```

### Response
#### Success Response (200)
- **cardBin** (object) - Information about the card BIN.
  - **bin** (string) - The card BIN.
  - **commercial** (boolean) - Whether the card is commercial.
  - **fundingSource** (string) - The funding source (e.g., "CREDIT").
  - **issuingBank** (string) - The issuing bank.
- **costEstimateAmount** (object) - The estimated cost amount.
  - **currency** (string) - Currency code.
  - **value** (integer) - Amount value.
- **costEstimateReference** (string) - A reference for the cost estimate.
- **resultCode** (string) - The result of the operation (e.g., "Success").
- **surchargeType** (string) - The type of surcharge applied (e.g., "INTERCHANGE_PLUS").

#### Response Example
```json
{
  "cardBin": { "bin": "411111", "commercial": false, "fundingSource": "CREDIT", "issuingBank": "Test Bank" },
  "costEstimateAmount": { "currency": "EUR", "value": 85 },
  "costEstimateReference": "8815323577089180",
  "resultCode": "Success",
  "surchargeType": "INTERCHANGE_PLUS"
}
```
```

--------------------------------

### Authorize Payment (Classic API v68)

Source: https://context7.com/adyen/adyen-openapi/llms.txt

Use this endpoint to authorize a payment. Ensure you have the correct API key and merchant account configured.

```bash
curl -X POST "https://pal-test.adyen.com/pal/servlet/Payment/v68/authorise" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "amount": { "currency": "EUR", "value": 2000 },
    "reference": "classic-auth-001",
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "card": {
      "number": "4111111111111111",
      "expiryMonth": "03",
      "expiryYear": "2030",
      "cvc": "737",
      "holderName": "John Smith"
    }
  }'
```

--------------------------------

### POST /sessions

Source: https://context7.com/adyen/adyen-openapi/llms.txt

Creates a payment session for the Adyen Drop-in or Components UI integration. The session encapsulates the full payment context; the client SDK uses the returned sessionData and id to render the payment UI and process the transaction without further server calls.

```APIDOC
## POST /sessions (v72)

### Description
Creates a payment session for the Adyen Drop-in or Components UI integration. The session encapsulates the full payment context; the client SDK uses the returned `sessionData` and `id` to render the payment UI and process the transaction without further server calls.

### Method
POST

### Endpoint
/v72/sessions

### Request Body
- **amount** (object) - Required - The transaction amount.
  - **currency** (string) - Required - The currency code.
  - **value** (integer) - Required - The transaction amount value.
- **countryCode** (string) - Required - The shopper's country code.
- **merchantAccount** (string) - Required - Your Adyen merchant account.
- **reference** (string) - Required - Your internal order reference.
- **returnUrl** (string) - Required - The URL to redirect the shopper to after the payment attempt.
- **channel** (string) - Optional - The channel of the transaction (e.g., "Web").
- **shopperReference** (string) - Optional - Your shopper reference.
- **shopperEmail** (string) - Optional - The shopper's email address.

### Request Example
```json
{
  "amount": { "currency": "USD", "value": 5000 },
  "countryCode": "US",
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "reference": "session-ref-001",
  "returnUrl": "https://your-company.com/return",
  "channel": "Web",
  "shopperReference": "shopper-123",
  "shopperEmail": "test@example.com"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the session.
- **sessionData** (string) - Data required by the client SDK to render the payment UI.
- **amount** (object) - The transaction amount.
  - **currency** (string) - The currency code.
  - **value** (integer) - The transaction amount value.
- **reference** (string) - Your internal order reference.
- **returnUrl** (string) - The URL to redirect the shopper to after the payment attempt.
- **expiresAt** (string) - The date and time when the session expires.

#### Response Example
```json
{
  "id": "CS000000000000001",
  "sessionData": "Ab02b4c0...==",
  "amount": { "currency": "USD", "value": 5000 },
  "reference": "session-ref-001",
  "returnUrl": "https://your-company.com/return",
  "expiresAt": "2023-12-01T12:00:00+00:00"
}
```
```

--------------------------------

### Configure a Sweep Rule using cURL

Source: https://context7.com/adyen/adyen-openapi/llms.txt

Set up an automatic sweep to move funds between balance accounts or to a bank account based on a trigger amount. Supports 'push' and 'pull' types.

```bash
curl -X POST "https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts/BAB8B2C3D4E5F6G7H8/sweeps" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "schedule": { "type": "daily" },
    "type": "push",
    "currency": "EUR",
    "triggerAmount": { "currency": "EUR", "value": 100000 },
    "targetAmount": { "currency": "EUR", "value": 0 },
    "counterparty": {
      "bankAccount": {
        "accountHolder": { "type": "organization", "companyName": "My Company BV" },
        "accountIdentification": {
          "type": "iban",
          "iban": "NL91ABNA0417164300"
        }
      }
    },
    "description": "Daily sweep to company bank account"
  }'
```

--------------------------------

### Issue a Payment Instrument (Card) using cURL

Source: https://context7.com/adyen/adyen-openapi/llms.txt

Create a virtual or physical payment card linked to a balance account. This is used for the Adyen Issuing product.

```bash
curl -X POST "https://balanceplatform-api-test.adyen.com/bcl/v2/paymentInstruments" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "type": "card",
    "issuingCountryCode": "NL",
    "balanceAccountId": "BAB8B2C3D4E5F6G7H8",
    "card": {
      "formFactor": "virtual",
      "brand": "mc",
      "configuration": {
        "cardholderName": "Jane Doe",
        "configurationProfileId": "CP000000000000001"
      }
    }'
```

--------------------------------

### POST /payments

Source: https://context7.com/adyen/adyen-openapi/llms.txt

Initiates an online payment using any supported payment method. This is the primary endpoint for card payments, wallets, and local payment methods. Returns a pspReference and a resultCode indicating the outcome.

```APIDOC
## POST /payments (v72)

### Description
Initiates an online payment using any supported payment method. This is the primary endpoint for card payments (including 3D Secure), wallets, and local payment methods. Returns a `pspReference` and a `resultCode` indicating the outcome (`Authorised`, `Pending`, `Received`, etc.).

### Method
POST

### Endpoint
/v72/payments

### Request Body
- **amount** (object) - Required - The transaction amount.
  - **currency** (string) - Required - The currency code.
  - **value** (integer) - Required - The transaction amount value.
- **reference** (string) - Required - Your internal order reference.
- **paymentMethod** (object) - Required - Details of the payment method.
  - **type** (string) - Required - The type of the payment method (e.g., "scheme").
  - **encryptedCardNumber** (string) - Required if type is "scheme" - Encrypted card number.
  - **encryptedExpiryMonth** (string) - Required if type is "scheme" - Encrypted expiry month.
  - **encryptedExpiryYear** (string) - Required if type is "scheme" - Encrypted expiry year.
  - **encryptedSecurityCode** (string) - Required if type is "scheme" - Encrypted security code.
- **returnUrl** (string) - Required - The URL to redirect the shopper to after the payment attempt.
- **merchantAccount** (string) - Required - Your Adyen merchant account.

### Request Example
```json
{
  "amount": {
    "currency": "EUR",
    "value": 1000
  },
  "reference": "YOUR_ORDER_NUMBER",
  "paymentMethod": {
    "type": "scheme",
    "encryptedCardNumber": "test_4111111111111111",
    "encryptedExpiryMonth": "test_03",
    "encryptedExpiryYear": "test_2030",
    "encryptedSecurityCode": "test_737"
  },
  "returnUrl": "https://your-company.com/checkout?shopperOrder=12xy",
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT"
}
```

### Response
#### Success Response (200)
- **pspReference** (string) - The Adyen-generated reference for the payment.
- **resultCode** (string) - The outcome of the payment attempt (e.g., "Authorised", "Pending").
- **amount** (object) - The transaction amount.
  - **currency** (string) - The currency code.
  - **value** (integer) - The transaction amount value.
- **merchantReference** (string) - Your internal order reference.

#### Response Example
```json
{
  "pspReference": "8515232733762537",
  "resultCode": "Authorised",
  "amount": { "currency": "EUR", "value": 1000 },
  "merchantReference": "YOUR_ORDER_NUMBER"
}
```
```

--------------------------------

### Create Balance Account

Source: https://context7.com/adyen/adyen-openapi/llms.txt

Creates a new balance account associated with an account holder. This account can hold funds and support multiple currencies.

```APIDOC
## POST /balanceAccounts (v2)

### Description
Creates a balance account under an account holder. Balance accounts hold funds and support multiple currencies. Each account holder can have multiple balance accounts with configurable sweep rules and transaction limits.

### Method
POST

### Endpoint
https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts

### Request Body
- **accountHolderId** (string) - Required - The ID of the account holder to which the balance account will be linked.
- **description** (string) - Optional - A description for the balance account.
- **reference** (string) - Optional - A reference for the balance account.
- **defaultCurrencyCode** (string) - Optional - The default currency code for the balance account (e.g., 'EUR').
- **metadata** (object) - Optional - Custom key-value pairs to store additional information.
  - **internalId** (string) - Example metadata field.

### Request Example
```json
{
  "accountHolderId": "AH3227C223222C5GXQXF68M5",
  "description": "Main EUR account",
  "reference": "balance-acct-001",
  "defaultCurrencyCode": "EUR",
  "metadata": { "internalId": "user-001" }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the newly created balance account.
- **accountHolderId** (string) - The ID of the associated account holder.
- **description** (string) - The description of the balance account.
- **status** (string) - The status of the balance account (e.g., 'active').
- **balances** (array) - An array of balance objects (initially empty).
- **defaultCurrencyCode** (string) - The default currency code of the balance account.

#### Response Example
```json
{
  "id": "BAB8B2C3D4E5F6G7H8",
  "accountHolderId": "AH3227C223222C5GXQXF68M5",
  "description": "Main EUR account",
  "status": "active",
  "balances": [],
  "defaultCurrencyCode": "EUR"
}
```
```

--------------------------------

### Integrate Adyen OpenAPI with Swagger Editor and Postman

Source: https://context7.com/adyen/adyen-openapi/llms.txt

Load Adyen's OpenAPI definition files directly into standard tools like Swagger Editor or Postman for easy integration and testing. The provided URLs allow direct import.

```bash
# --- Option 1: Swagger Editor (web) ---
# Upload the file at https://editor.swagger.io/ or load by URL:
# https://raw.githubusercontent.com/Adyen/adyen-openapi/main/json/CheckoutService-v72.json

# --- Option 2: Postman import ---
# Import via Postman UI: File > Import > Link
# URL: https://raw.githubusercontent.com/Adyen/adyen-openapi/main/json/CheckoutService-v72.json
```

--------------------------------

### Create Payment Session - Checkout API

Source: https://context7.com/adyen/adyen-openapi/llms.txt

Creates a payment session for Adyen's Drop-in or Components UI. The client SDK uses the returned session data to render the payment UI and process the transaction.

```bash
curl -X POST "https://checkout-test.adyen.com/v72/sessions" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "amount": { "currency": "USD", "value": 5000 },
    "countryCode": "US",
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "reference": "session-ref-001",
    "returnUrl": "https://your-company.com/return",
    "channel": "Web",
    "shopperReference": "shopper-123",
    "shopperEmail": "test@example.com"
  }'
```