Skip to main content

ValPay Merchant Onboarding API: User Guide

How to create a merchant with POST /v1/adyen/merchants: required fields, a full example request, the response and what happens next.

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:

  1. ValPay creates the merchant record and its stores.

  2. The merchant email and each contract recipient receive the contract, with the ValPay T&C and a fee summary.

  3. The merchant signs the T&C and is sent to the Adyen-hosted onboarding page (the KYC link).

  4. On that page the merchant adds company details, decision makers and bank details, then signs Adyen’s agreements.

  5. 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:

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

legalEntity

object

Yes

The business or person being verified. Type plus one or two matching blocks.

businessLine

object

Yes

industryCode for the business.

merchantName

object

Yes

Legal name plus the contact’s first and last name.

gmv

integer

Yes

Annual gross merchandise volume. Positive whole number.

merchantEmail

string

Yes

Primary contact. Receives the contract and KYC link.

brand

string

Yes

Name key of the brand the merchant belongs to, for example progitek. Not the brand’s ID.

netNew

enum

Yes

NET_NEW, ERP or ERP_PLUS_PAYMENTS.

contract

object

Yes

T&C document, terms and recipients.

stores

array

Yes

One or more stores, each with address, fees and sales channels.

preferredLanguage

enum

No

en or fr. Language of the Adyen KYC page. Defaults to the brand’s locale.

kycReturnUrl

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.

type

Blocks to include

Use for

organization

organization

A company, non-profit or other registered body

individual

individual

A person with no registered business

soleProprietorship

soleProprietorship and individual

A business owned by one person. ValPay creates both legal entities in Adyen and links them.

Field

Required

Description

organization.legalName

Yes

Registered business name

organization.registeredAddress

Yes

Address object, below

individual.firstName, individual.lastName

Yes

The person, or the sole proprietor

individual.residentialAddress

Yes

Home address, as an address object

soleProprietorship.legalName

Yes

Business name

soleProprietorship.registeredAddress

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

street

Yes

Street and number

street2

No

Suite, floor, unit

city

Yes

stateOrProvince

US, CA, AU, PR

Two or three letter code, for example QC

postalCode

Yes

country

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

merchantName.legalName

Yes

Usually the same as the legal entity’s name

merchantName.firstName

Yes

Contact who signs the T&C

merchantName.lastName

Yes

merchantEmail

Yes

Receives the contract and KYC link

brand

Yes

The brand’s name key, for example progitek (see Onboarding API: looking up brands)

businessLine.industryCode

Yes

gmv

Yes

Annual volume as a whole number above 0: 1000000, not "1,000,000"

netNew

Yes

NET_NEW, ERP (ERP only) or ERP_PLUS_PAYMENTS

preferredLanguage

No

en or fr. Language of the KYC page; defaults to the brand’s locale.

kycReturnUrl

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

contract.tcDocument

Yes

The T&C filename for the merchant’s region, for example ValPay-T&C-CA-English-2025.pdf (see Onboarding API: supported countries and regions)

contract.initialTerm

Yes

Initial term in months, as a number

contract.renewalTerm

Yes

Renewal term in months, as a number

contract.recipients

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

storeName

Yes

The store’s name

settlementTime

Yes

24-hour time, for example "22:00"

address

Yes

Store address object, below

discounting

Yes

The store’s fee profile (see Onboarding API: fee profiles)

businessLine.industryCode

Yes

Usually the business’s code (see Onboarding API: looking up industry codes)

businessLine.salesChannels

Yes

Non-empty list, for example ["pos"]. Values include pos, posMoto, eCommerce, ecomMoto and payByLink.

businessLine.webData

Yes

The store’s websites, each { "webAddress": "https://…" }. Send [] for a store with no website.

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

line1

Yes

Street and number

line2

No

Suite, floor, unit

city

Yes

stateOrProvince

US, CA, AU, PR

Two or three letter code

postalCode

Yes

country

Yes

Two-letter code

phoneNumber

Yes

The store’s phone number in international format, for example +15145550100

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

data.uuid

The merchant ID to use with other endpoints

data.subMerchantID

Sub-merchant ID, for example 44034AD4@5D2FCA03

data.onboarding.kycUrl

Link to the merchant’s Adyen-hosted onboarding (KYC) page

data.onboarding.contractUrl

Link to the merchant’s generated contract

data.onboarding.status

approved (false at first), issues, events, isPayoutBlocked

data.onboarding.stores[]

Each store as submitted, plus warnings and failureState

data.externalReference.providers[]

Adyen IDs: legalEntityID, accountHolderID and businessLineID. The business line value is a JSON string holding a list.

data.agreements[]

Agreements to sign, each { type, signed }

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.agreements lists each one as { "type": …, "signed": false }: VALPAY_TC, ADYEN_SERVICE_AGREEMENT and, when it applies, ADYEN_PCI_DSS. They are signed through the Agreements endpoints. If you lose the response, refetch them with GET /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.contractUrl links to the merchant’s generated contract.

  • Status. data.onboarding.status.approved stays false until ValPay and Adyen approve the merchant. Track approval on the merchant’s timeline in the ValPay portal, or read the record later with GET /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.

Did this answer your question?