Developers

Search for documents

Dev

Merchants

Operations related to merchants and merchant onboarding

All endpoints require a JWT Bearer token in the Authorization header; most also require an API key in the X-API-KEY header.

GET `/v1/merchants`

Get a list of merchants with pagination

Parameters

Name	In	Type	Required	Description
`limit`	query	`integer`	Yes	Maximum number of records to return. Starts from 1 to 1000.
`page`	query	`integer`	Yes	Page number to retrieve, starting from 0.
`selectFields`	query	`string`	No	Choose specific fields to include in the response (comma-separated). If provided, excludeFields will be ignored.
`excludeFields`	query	`string`	No	Exclude specific fields from the response (comma-separated).
`filter`	query	`string`	No	Filter merchants using MongoDB Query Language (MQL) format.
`sort`	query	`string`	No	Sort merchants using MongoDB Query Language (MQL) format.
`populateOptions`	query	`string`	No	Include related data in query results using a JSON object.

Responses

Status	Description
`200`	Successfully retrieved a paginated list of merchants.

GET `/v1/merchants/{id}`

Get a specific merchant by ID

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes	The uuid field
`enriched`	query	`boolean`	No	Include payment processor account and details in the response
`selectFields`	query	`string`	No	Choose specific fields to include in the response (comma-separated). If provided, excludeFields will be ignored.
`excludeFields`	query	`string`	No	Exclude specific fields from the response (comma-separated).
`populateOptions`	query	`string`	No	Include related data in query results using a JSON object.

Responses

Status	Description
`200`	Merchant details retrieved successfully

The following endpoint is served from https://onboarding.valpay.com and accepts either a JWT Bearer token in the Authorization header or an API key in the X-API-KEY header.

POST `/v1/adyen/merchants`

Create a merchant

Creates a merchant with one or more stores and triggers Adyen KYC.

On success, the merchant receives:

a KYC verification link (Adyen Hosted Onboarding Page) via email,

a contract via email from each recipient address.

Authentication: Bearer token or API key in the X-API-KEY header.

Legal entity model

Every merchant needs a legalEntity of one of three types.

`type`	Required blocks	Describes
`organization`	`organization`	A company (private, non-profit, etc.)
`individual`	`individual`	A natural person
`soleProprietorship`	both `soleProprietorship` and `individual`	A business owned by one person. Adyen models this as two linked legal entities — we create both and associate them in a single request on your behalf.

Supported countries

Code	Country
`US`	United States
`CA`	Canada
`GB`	United Kingdom
`AU`	Australia
`NZ`	New Zealand
`HK`	Hong Kong
`IE`	Ireland
`AT`	Austria
`BE`	Belgium
`CH`	Switzerland
`DE`	Germany
`FR`	France
`IT`	Italy
`LU`	Luxembourg
`NL`	Netherlands
`PT`	Portugal

Terms & Conditions

The contract.tcDocument filename must match the legal entity's country region.

Region	Countries	Example filename
US	US	`ValPay-T&C-US-English-2025.pdf`
CA	CA	`ValPay-T&C-CA-English-2025.pdf`
AU	AU, NZ, HK	`ValPay-T&C-AU-English-2025.pdf`
UK	GB	`ValPay-T&C-UK-English-2025.pdf`
EU	AT, BE, CH, DE, FR, IE, IT, LU, NL, PT	`ValPay-T&C-EU-Italian-2025.pdf` or `ValPay-T&C-EU-German-2025.pdf`

Rates and fees

Enter all rates as decimal percentages: 0.05 means 5%, 0.0105 means 1.05%. Up to 4 decimal places.

Tier	Countries	Chargeback / ACH return
1	US, GB, EU countries	10–50
2	CA, AU, NZ	10–100
3	HK	50–500 (ACH must be `0` — ACH disabled)

ACH is also disabled (must be 0) in AT, BE, CH, DE, FR, IT, LU, NL, PT.

Industry codes

The industryCode field (on both businessLine and stores[].businessLine) must be one of the 251 supported codes listed in the API spec at https://onboarding.valpay.com/api-docs/. If the brand you're onboarding under has a restricted list, only those codes are accepted.

Request body (required)

Field	Type	Required	Description
`legalEntity`	`object`	Yes	Legal entity information. The block(s) required depend on `type`: - `type: organization` → include `organization`. - `type: individual` → include `individual`. - `type: soleProprietorship` → include both `soleProprietorship` (the business) and `individual` (the sole proprietor). Adyen models a sole proprietorship as two linked legal entities; we create the individual, create the business, and associate them in one API call on your behalf. Any block that doesn't match the declared `type` is rejected.
`businessLine`	`object`	Yes
`merchantName`	`object`	Yes
`gmv`	`integer`	Yes	Gross Merchandise Volume (annual). Must be a positive integer.
`merchantEmail`	`string`	Yes	Primary contact email for the merchant
`brand`	`string`	Yes	Brand the merchant belongs to
`netNew`	`string (enum)`	Yes	Merchant acquisition type One of: `NET_NEW`, `ERP`, `ERP_PLUS_PAYMENTS`
`contract`	`object`	Yes
`stores`	`array<object>`	Yes	One or more stores to create for this merchant
`preferredLanguage`	`string (enum)`	No	Merchant-level language preference used to localize the Adyen-hosted onboarding page. Optional; when omitted, the generated kycUrl falls back to the brand's default locale. One of: `en`, `fr`

Responses

Status	Description
`201`	Merchant created successfully. The response `data` contains the created merchant record and an `agreements` array listing every onboarding agreement the merchant must accept (Valpay T&C, Adyen Service Agreement, and Adyen PCI DSS when applicable). If you lose the response, refetch via `GET /v1/adyen/merchants/:merchant_id/agreements`.
`400`	Invalid request — one or more fields failed validation
`401`	Authentication failed — missing or invalid credentials
`409`	Conflict — a merchant with the same legal name already exists
`429`	Rate limit exceeded

Response schema (2xx)

Field	Type	Required	Description
`success`	`boolean`	No
`data`	`object`	No	The created merchant record
`message`	`string`	No

Examples

GET `/v1/merchants`

curl "https://api.valpay.com/v1/merchants?limit=10&page=0&selectFields=uuid,merchantName,brand" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

curl "https://api.valpay.com/v1/merchants?limit=10&page=0&selectFields=uuid,merchantName,brand" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

curl "https://api.valpay.com/v1/merchants?limit=10&page=0&selectFields=uuid,merchantName,brand" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

Response 200 (illustrative):

{
  "data": [
    {
      "uuid": "8f14e45f-ceea-467f-a1d6-2f9a1e6b0c01",
      "merchantName": { "legalName": "Example Retail LLC" },
      "brand": "665f1e2a9c8b4a0012d3e4f5"
    }
  ],
  "total": 57,
  "page": 0,
  "limit": 10
}

{
  "data": [
    {
      "uuid": "8f14e45f-ceea-467f-a1d6-2f9a1e6b0c01",
      "merchantName": { "legalName": "Example Retail LLC" },
      "brand": "665f1e2a9c8b4a0012d3e4f5"
    }
  ],
  "total": 57,
  "page": 0,
  "limit": 10
}

{
  "data": [
    {
      "uuid": "8f14e45f-ceea-467f-a1d6-2f9a1e6b0c01",
      "merchantName": { "legalName": "Example Retail LLC" },
      "brand": "665f1e2a9c8b4a0012d3e4f5"
    }
  ],
  "total": 57,
  "page": 0,
  "limit": 10
}

GET `/v1/merchants/{id}`

curl "https://api.valpay.com/v1/merchants/8f14e45f-ceea-467f-a1d6-2f9a1e6b0c01?enriched=true" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

curl "https://api.valpay.com/v1/merchants/8f14e45f-ceea-467f-a1d6-2f9a1e6b0c01?enriched=true" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

curl "https://api.valpay.com/v1/merchants/8f14e45f-ceea-467f-a1d6-2f9a1e6b0c01?enriched=true" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-API-KEY: YOUR_API_KEY"

Response 200: the merchant object, enriched with payment processor account details.

POST `/v1/adyen/merchants`

Create an organization merchant with one store (abbreviated body):

curl -X POST https://onboarding.valpay.com/v1/adyen/merchants \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "legalEntity": {
      "type": "organization",
      "organization": { "legalName": "Example Retail LLC", "countryCode": "US" }
    },
    "businessLine": { "industryCode": "722511" },
    "merchantName": { "legalName": "Example Retail LLC" },
    "gmv": 1200000,
    "merchantEmail": "owner@example.com",
    "brand": "665f1e2a9c8b4a0012d3e4f5",
    "netNew": "NET_NEW",
    "contract": { "tcDocument": "ValPay-T&C-US-English-2025.pdf" },
    "stores": [ { "name": "Main Street Store", "businessLine": { "industryCode": "722511" } } ]
  }'

curl -X POST https://onboarding.valpay.com/v1/adyen/merchants \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "legalEntity": {
      "type": "organization",
      "organization": { "legalName": "Example Retail LLC", "countryCode": "US" }
    },
    "businessLine": { "industryCode": "722511" },
    "merchantName": { "legalName": "Example Retail LLC" },
    "gmv": 1200000,
    "merchantEmail": "owner@example.com",
    "brand": "665f1e2a9c8b4a0012d3e4f5",
    "netNew": "NET_NEW",
    "contract": { "tcDocument": "ValPay-T&C-US-English-2025.pdf" },
    "stores": [ { "name": "Main Street Store", "businessLine": { "industryCode": "722511" } } ]
  }'

curl -X POST https://onboarding.valpay.com/v1/adyen/merchants \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "legalEntity": {
      "type": "organization",
      "organization": { "legalName": "Example Retail LLC", "countryCode": "US" }
    },
    "businessLine": { "industryCode": "722511" },
    "merchantName": { "legalName": "Example Retail LLC" },
    "gmv": 1200000,
    "merchantEmail": "owner@example.com",
    "brand": "665f1e2a9c8b4a0012d3e4f5",
    "netNew": "NET_NEW",
    "contract": { "tcDocument": "ValPay-T&C-US-English-2025.pdf" },
    "stores": [ { "name": "Main Street Store", "businessLine": { "industryCode": "722511" } } ]
  }'