Overview
One call, POST /v1/adyen/merchants on the onboarding host, creates a merchant with one or more stores and starts Adyen KYC. Test and production behave the same: every successful call creates the merchant and sends the contract and KYC emails. Build against the test environment, then move to production (see Onboarding API: authentication and environments).
What happens after a successful call:
ValPay creates the merchant record and its stores.
The merchant email and each contract recipient receive the contract, with the ValPay T&C and a fee summary.
The merchant signs the T&C and is sent to the Adyen-hosted onboarding page (the KYC link).
On that page the merchant adds company details, decision makers and bank details, then signs Adyen’s agreements.
ValPay and Adyen review the application. Approval status shows on the merchant’s timeline in the ValPay portal.
The API creates the same application a sales agent submits through portal.valpay.com, so the fields mirror the portal’s application form.
Authentication and environments
Send each request with one credential, a JWT in Authorization: Bearer <token> or an API key in X-API-KEY, not both. Merchants are created on the onboarding host: https://onboarding.valpay.dev for test and https://onboarding.valpay.com for production. Hosts and credentials are covered in Onboarding API: authentication and environments.
Before you start
Gather these before building a request:
Brand. The brand’s name key, for example
progitek. See Onboarding API: looking up brands.Industry code. One of the supported codes, for example
6212. See Onboarding API: looking up industry codes.Country and T&C document. The merchant must be in a supported country, and the contract uses that country’s T&C document. See Onboarding API: supported countries and regions.
Fee profile. The rates and fees for each store. See Onboarding API: fee profiles.
Request at a glance
The body has nine required top-level fields and two optional ones. The sections below cover each object field by field.
Field | Type | Required | What it holds |
| object | Yes | The business or person being verified. Type plus one or two matching blocks. |
| object | Yes |
|
| object | Yes | Legal name plus the contact’s first and last name. |
| integer | Yes | Annual gross merchandise volume. Positive whole number. |
| string | Yes | Primary contact. Receives the contract and KYC link. |
| string | Yes | Name key of the brand the merchant belongs to, for example progitek. Not the brand’s ID. |
| enum | Yes |
|
| object | Yes | T&C document, terms and recipients. |
| array | Yes | One or more stores, each with address, fees and sales channels. |
| enum | No |
|
| string | No | HTTPS URL the merchant returns to after KYC. Defaults to valpay.com. |
The validator is strict on some objects: unknown keys inside legalEntity.organization are rejected, not ignored.
Legal entity
legalEntity.type picks one of three shapes. Include only the blocks that type needs; any other block is rejected.
| Blocks to include | Use for |
|
| A company, non-profit or other registered body |
|
| A person with no registered business |
|
| A business owned by one person. ValPay creates both legal entities in Adyen and links them. |
Field | Required | Description |
| Yes | Registered business name |
| Yes | Address object, below |
| Yes | The person, or the sole proprietor |
| Yes | Home address, as an address object |
| Yes | Business name |
| Yes | Address object, below |
The merchant’s country comes from its address; there’s no separate country field.
Address object for registeredAddress and residentialAddress. Stores use a different address shape (see Stores).
Field | Required | Description |
| Yes | Street and number |
| No | Suite, floor, unit |
| Yes |
|
| US, CA, AU, PR | Two or three letter code, for example |
| Yes |
|
| Yes | Two-letter code of a supported country (see Onboarding API: supported countries and regions) |
Merchant and contact
merchantName holds both the business name and the person who signs the contract.
Field | Required | Description |
| Yes | Usually the same as the legal entity’s name |
| Yes | Contact who signs the T&C |
| Yes |
|
| Yes | Receives the contract and KYC link |
| Yes | The brand’s name key, for example |
| Yes | |
| Yes | Annual volume as a whole number above 0: |
| Yes |
|
| No |
|
| No | HTTPS URL the merchant returns to after KYC; defaults to valpay.com |
Contract
The contract needs the T&C document for the merchant’s region, both terms, and a recipients list.
Field | Required | Description |
| Yes | The T&C filename for the merchant’s region, for example |
| Yes | Initial term in months, as a number |
| Yes | Renewal term in months, as a number |
| Yes | List of email addresses that also receive the contract. Can be empty. |
Stores
stores needs at least one entry, and each store carries its own address, fee profile and sales channels.
Field | Required | Description |
| Yes | The store’s name |
| Yes | 24-hour time, for example |
| Yes | Store address object, below |
| Yes | The store’s fee profile (see Onboarding API: fee profiles) |
| Yes | Usually the business’s code (see Onboarding API: looking up industry codes) |
| Yes | Non-empty list, for example |
| Yes | The store’s websites, each |
Store address object. It differs from the legal entity’s address: line1 and line2 replace street and street2, and the store’s phone number goes inside it.
Field | Required | Description |
| Yes | Street and number |
| No | Suite, floor, unit |
| Yes |
|
| US, CA, AU, PR | Two or three letter code |
| Yes |
|
| Yes | Two-letter code |
| Yes | The store’s phone number in international format, for example |
Fees
Each store’s discounting object is its fee profile: a name, billing cycle, rate type, chargeback and ACH return fees, and a rate for each card type and card state. Rates are decimal fractions (0.0265 is 2.65%), and fees must fall inside the country’s tier. All fields and an example are in Onboarding API: fee profiles; the tiers are in Onboarding API: supported countries and regions.
Full example request
This request creates a Canadian organization with one in-person store on the test host.
curl -X POST https://onboarding.valpay.dev/v1/adyen/merchants \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"legalEntity": {
"type": "organization",
"organization": {
"legalName": "Example Software Inc.",
"registeredAddress": {
"street": "1234 Rue Principale",
"city": "Montréal",
"stateOrProvince": "QC",
"postalCode": "H2X 1Y4",
"country": "CA"
}
}
},
"businessLine": { "industryCode": "6212" },
"merchantName": {
"legalName": "Example Software Inc.",
"firstName": "Jane",
"lastName": "Tremblay"
},
"gmv": 1000000,
"merchantEmail": "[email protected]",
"brand": "your-brand-name",
"netNew": "NET_NEW",
"contract": {
"tcDocument": "ValPay-T&C-CA-English-2025.pdf",
"initialTerm": 12,
"renewalTerm": 12,
"recipients": []
},
"stores": [
{
"storeName": "Example Software Store",
"settlementTime": "22:00",
"address": {
"line1": "1234 Rue Principale",
"city": "Montréal",
"stateOrProvince": "QC",
"postalCode": "H2X 1Y4",
"country": "CA",
"phoneNumber": "+15145550100"
},
"discounting": {
"name": "Standard CA card present",
"cycle": "DAILY",
"rateType": "FLAT",
"chargebackFee": 35,
"achReturnFee": 35,
"feeProfiles": [
{ "cardType": "VISA", "cardState": "CARD_PRESENT", "rate": 0.0265, "crossborderRate": 0, "transactionFee": 0 }
],
"cardTypesToEnable": {},
"amexType": "OPT_BLUE"
},
"businessLine": {
"industryCode": "6212",
"salesChannels": ["pos"],
"webData": []
}
}
],
"preferredLanguage": "en"
}'
Responses
A successful create returns 201 with the stored merchant in data and message: "Merchant created successfully". A 409 means a merchant with this legal name already exists. Error formats and the other status codes are in Onboarding API: errors and status codes.
Successful response
The stored record names some fields differently from the request: legalName and email sit at the top level, and the contact person is under name.
Field | What it holds |
| The merchant ID to use with other endpoints |
| Sub-merchant ID, for example |
| Link to the merchant’s Adyen-hosted onboarding (KYC) page |
| Link to the merchant’s generated contract |
|
|
| Each store as submitted, plus |
| Adyen IDs: |
| Agreements to sign, each |
After creation
Keep the merchant ID and the agreements list from the 201 response; the merchant can’t go live until every agreement is accepted.
Agreements.
data.agreementslists each one as{ "type": …, "signed": false }:VALPAY_TC,ADYEN_SERVICE_AGREEMENTand, when it applies,ADYEN_PCI_DSS. They are signed through the Agreements endpoints. If you lose the response, refetch them withGET /v1/adyen/merchants/{merchant_id}/agreements.KYC link. The response includes it as
data.onboarding.kycUrl, so you can send or embed it yourself; the merchant also gets it by email. On that page they add company details, decision makers (a controlling person, every owner above 25% and a signatory) and bank details.Contract.
data.onboarding.contractUrllinks to the merchant’s generated contract.Status.
data.onboarding.status.approvedstaysfalseuntil ValPay and Adyen approve the merchant. Track approval on the merchant’s timeline in the ValPay portal, or read the record later withGET /v1/merchants/{id}?enriched=true.Next steps. After approval: order and assign terminals, run a test transaction and add merchant admin users in the portal.
