As a System Integrator (SI), you play a vital role in the Adyen ecosystem. While the integration you have built is your own, the documentation you provide is the primary bridge between our shared technology and the user’s success. This guide is designed to help you align your technical content with the Adyen Standard of Excellence. By following these principles, you ensure that your documentation is accessible, scalable, and professional.

How to use this guide

This style guide is not a rigid set of rules, but a framework for clarity. Use it as a reference when drafting new integration guides, updating README files, or creating configuration tutorials.

What’s inside?

To help you navigate these standards, we have categorized our requirements into the following pillars:

• Adyen content guidelines: The gold standard for technical writing at Adyen.

• Technical Formatting: Specific rules for Placeholders and Link text to ensure users can copy-paste with confidence.

• Information Architecture: A recommended structure for your pages to ensure a logical flow.

Adyen content guidelines

Plain English

English is a common language of work and education for billions of people. For 80% of them English is not their native language. By sticking to the following rules, you enable readers to process your text easily so they can focus on the content.

One word, one meaning

• Use the same name for the same thing
  If you first use synonym A and later synonym B, it is possible that readers think these are two different things.
  It is okay to use a shorter version of a phrase you used earlier.

• Use a word in only one of its meanings
  It can confuse readers for a moment when you use a single word in meaning A and meaning B.

• Do not use a word both as a noun and a verb
  It can confuse readers when you use the same word both as a noun and as a verb.
  For example: display, filter, grant, link, list, request, store.

  • Use request only as a noun. You can use verbs like 'ask' or 'get' instead of 'request' as a verb.
    Incorrect: To request access, send a POST /access request.
    Correct: To get access, send a POST /access request.

    Incorrect: Contact our Support team to request this feature.
    Correct: Ask our Support team to enable this feature.

  • Use display only as a noun. The context is usually payment terminal hardware.
    You can use verbs like 'show', 'appear', or 'include' instead of 'display' as a verb.

    Incorrect: You can display the express checkout button on your cart page.
    Correct: You can show the express checkout button on your cart page.

  • Avoid store as a verb. Do not use 'store' both as a verb and a noun on the same page. Do not use 'store' as a verb on the same page as parameters that refer to 'store' as a noun.
    You can use 'save' instead of 'store' as a verb.

    Incorrect: Store the storeID in your back-end system.
    Correct: Save the storeID in your back-end system.

  • Do not use filter, grant, link, list and similar cases both as a noun and a verb in the same paragraph.

• Use a word in its most common meaning
  In a dictionary, the most common meaning is the first one listed for the word.
  For example, as is often used in the meaning of because. But in the dictionary this is only the fourth meaning of as as a conjunction, and as is also used as an adverb, pronoun, and preposition.

Use plain words

• Use everyday English words if possible
  Scientific words or jargon words are more difficult to understand than plain words.

• Use jargon where this is efficient
  When you use jargon words, ask yourself if you and the reader know what the jargon word means. If necessary, explain the jargon word or add a link to a terminology list.

• Do not use a long word where a short one will do
  Long words are more difficult to read and therefore distract from the content.

• Avoid Latin phrases and abbreviations
  To avoid misinterpretation, use common English words instead of Latin phrases and Latin abbreviations as much as possible. The abbreviations e.g. (= exempli gratia) and i.e. (= id est) in particular are often used incorrectly or misunderstood.

  Do not use	Do use
  ad hoc	when necessary when needed
  de facto	actual in fact
  per	for each by
  prior to	before
  via	using through
  versus / vs	compared to
  e.g.	for example such as like
  i.e.	in other words namely

Keep it short

• Use no more than 20 to 25 words per sentence
  Cut out superfluous words or split up the sentence.

• Express only one idea per sentence
  Split up sentences, or format text as a list.

• Acronyms can be very handy and are definitely short, but do not always improve the reader's understanding of the text. It is OK to use an acronym for an industry standard term that is commonly presented as an acronym. (Do spell out the full term followed by the acronym in parentheses the first time it occurs on a page.) Avoid using an acronym for Adyen-specific jargon, because the reader is not familiar with the jargon, let alone with the acronym.

Keep it simple

• Write complete sentences with a simple grammatical structure

• Avoid subordinate clauses
  A subordinate clause is an incomplete sentence embedded in a sentence. They increase cognitive load because the reader has to remember a lot.

• Avoid future tense
  Often there is no real need to indicate something happens in the future. A sentence in the present tense is easier to read.
  Incorrect: You will need to change your client-side implementation.
  Correct: You need to change your client-side implementation.

  Note that will is not only a marker of future tense. It also expresses modality (see below).

• Avoid modal verbs
  Non-native speakers of English often misinterpret could , should , would , shall , will , may , and might . The words can and must cause less problems because these resemble auxiliary verbs in some other languages.

• Avoid stacked premodifiers
  Premodifiers are words placed before a noun, describing that noun. They make the sentence shorter, but also more difficult to read and often ambiguous.
  Incorrect: ... the TraceMark server rear panel power switch.
  Correct: ... the power switch on the rear panel of the TraceMark server.

• Avoid the '-ing' form of verbs
  What's wrong with using the present continuous in your writing?

  • The general advice from controlled English initiatives is to use as few different verb tenses as possible. That makes the text easier to read.
  • As a verb tense, the present continuous indicates that an action is happening now. In our kind of content we seldomly need to indicate that.
  • The '-ing' form can create a nominalization (like "writing" above). This takes the action out of the sentence and makes the sentence a little less engaging.

• Avoid certain contractions
  Do not use 's. It can cause confusion to use 's because it can be the contraction of 'is', 'has', or 'us', and many people are a little uncertain about it's and its.

  Use the full versions cannot and do not instead of can't and don't.

Keep it active

Keeping the text active makes it more concrete and easier to read.

• Use active voice
  Passive voice can still be useful, for example, when it is unnecessary, undesirable, or impossible to say who performs the action.

• Address the reader directly
  As a rule of thumb, address the reader as "you". But also consider whether it is a user performing an action, or their application.
  For example, a user builds an application that receives and handles webhooks. So do we send a webhook message to "you" (the developer reading the docs)? Or do we send it to their application?

• Avoid nominalizations
  A nominalization is a verb turned into a noun. Too much nominalization takes the action out of a text and makes the text sound unnecessarily formal.
  Incorrect: conduct an investigation
  Correct: investigate

Give clear instructions

Readers do not follow instructions if they do not recognize instructions as such. To help readers recognize instructions:

• Give instructions in the imperative voice

• Use numbered steps
  Start each instruction step with a number, so that readers immediately see where the instructions are on a page.
  If there is information belonging to the instruction step, indent the text at the same level as the instruction step (so do not outdent) and do not number the additional information as a step.

  If there seems to be only one step, be creative in adding another step. For example, it is sometimes argued that sending an API request and receiving the response is one step because the response comes automatically. However, there is always something of interest in the response. You can easily turn this into a step. For example, "2. In the response, note XXX. You need this when ...". or "2. Check that the response contains XXX. This confirms ..."

• Use a heading that contains a verb in the imperative voice

• Do not hide instructions
  Common hideouts for instructions are passive voice, descriptions, notes, cautions, warnings, or sidebars.

• In some cases, use an introductory phrase
  Present the instructions with an introductory phrase that helps the user to better understand the outcome. To save words, use an ellipsis with a colon instead of a full sentence. For example: use "To create an account:" instead of "To create an account, follow these steps:". Note that this guideline differs from the Microsoft style guide.

  Omit the introductory phrase if the instructions immediately follow a heading that contains a verb in the imperative voice.

• Specify the location of the action at the beginning of the step
  To orient the users, start with telling them where to perform an action.
  Incorrect: 1. Select Create account on the Accounts page.
  Correct: 1. On the Accounts page, select Create account.

  Do not present the location as the step result of a previous action, as in:
  Incorrect: "1. Select the company. The Accounts page opens. 2. Select Create account."

  Omit the location if this is very evident or has been mentioned in a previous step.

• Do not use directional information unless required
  It can be useful to specify the location of an action. However, directional language, such as above, below, or left, is often not needed or helpful. As a general guideline, do not include directional information in instructions. Some exceptions are:

  • When the reader must scroll a lot. ("At the bottom of the page, select Save.")
  • When the UI has two or more elements with the same name, such as a field and a pane both called Your order.

  If a UI element is hard to find, provide feedback to the developers or designers.

Word Choice

To improve readability and comprehension in documentation, choose your words wisely and use them consistently. If you mean the same thing, use the same word.

For general guidance on spelling and word choice, use the following resources:

• The Microsoft Writing Style Guide. There are a couple of exceptions though.
• The American Heritage Dictionary. This is Microsoft's preferred dictionary.

Exceptions to US English

We always use US English in our documentation, except when citing elements that do not follow US spelling guidelines.

For example, the /authorise endpoint is spelled with an 's' (this is not US English). In a sentence, you can say:

"You can use the /authorise endpoint to authorize a payment."

For cancel the US English spelling is with a single l in the verb endings cancel, canceled, and canceling, but with a double l in the noun cancellation.

Placeholder text and numbers

Use standard placeholder values for email address, IP address, and phone number.

Example URL

Use example.com as an example domain. Because example.com is reserved and cannot be transferred to any other entity.

For example:

• your-company.example.com/checkout?shopperOrder=12xy..
• your-platform.example.com/payout?submerchant=blah
• any-subdomain.example.com

Email address

Use an email address in the format *@example.com (where * is a wildcard).

When using a placeholder for a shopper email address, use s.hopper@example.com.

If you are documenting a scenario where an email address needs to be provided by a merchant, sub-merchant, or supplier, consider using an email address that reflects this instead.

IP address

When referring to an external IP address, use one of the addresses below. These addresses have been reserved for documentation purposes by the IETF.

IPv4 addresses

For IPv4 addresses, use either:

• 192.0.2.1
• 198.51.100.1
• 203.0.113.1

For ranges, use one of the following:

• 192.0.2.0/24
• 198.51.100.0/24
• 203.0.113.0/24

IPv6 addresses

If you need to use an IPv6 address, use one of the following reserved addresses:

• 2001:db8::
• 2001:db8:ffff:ffff:ffff:ffff:ffff:ffff
• 2001:db8:1:1:1:1:1:1
• 2001:db8:2:2:2:2:2:2
• 2001:db8:3:3:3:3:3:3
• 2001:db8:4:4:4:4:4:4

For ranges, use:

• 2001:db8::/32

Phone number

Use a neutral placeholder example like 123456789 that matches the validation of the API.

Numbers

For general guidance on whether you should use a numeral (5) or a word (five), follow the guidance on Numbers in the Microsoft Writing Style Guide.

There's an exception to these guidelines if the number is used when referring to a specific term, such as Level 2 Data, or PCI Compliance Level 1.

Versioning

In accordance with the Microsoft Writing Style Guide, use or earlier and or later to refer to versions in reference to the one you mention. For example:

The feature is available in v5.0.0 or earlier.
The feature is available in v5.0.0 or later.

That and which

That and which are often confused. As a rule of thumb, if you are unsure use that.

You can use which at the beginning of a clause that adds supporting or parenthetical information. For example, "Your package contains the subsidiary information card, which you can use to obtain device drivers or local technical support."

For more information, see that vs. which in the Microsoft Writing Style Guide.

Monetary amounts

When specifying a monetary amount and its currency, use the following format:

Currency code — non-breaking space — amount. For example: EUR 100

For the non-breaking space you can type   in the Markdown file (for example: EUR 100) or you can press Option + Spacebar on your Mac.

Do not use the currency symbol.

Enable, turn on, allow

The MS style guide recommends using "turn on" or "allow" instead of "enable" when describing making a feature or setting available. However, these terms are context-dependent.

• When referring to a setting in a UI that has an enable option, be consistent with the UI and talk about enabling the setting rather than turning it on.
• When the user must turn on more than one toggle or setting to be able to use a feature, talk about enabling a feature rather than turning on a feature, so that the reader doesn't think it is simply flipping a switch.
• The word "allow" often comes with the connotation of giving permission. Use allow when talking about making permissions available, for example in the context of roles.

Log in/out

Use log in and log out because:

• Most instances are in relation with the Customer Area, which has a Log in button.
• There is no added benefit for the readers if we switch to sign in/out.

Log into your Customer Area.
Log in to your Customer Area.

Text formatting when referring to code

Endpoints

Endpoint names should start with a forward slash.

Correct	Incorrect
the /payments endpoint.	the /payments endpoint.
	the /payments endpoint.
	the payments endpoint.

Parameters

Use monospace when referring to elements of an API or SDK.

Correct	Incorrect
use the additionalData field	use the additionalData field
	use the "additionalData" field
	use the additionalData field

Use bold text when referring to values.

Correct	Incorrect
specify a value of 4111111111111111.	specify a value of 4111111111111111.
	specify a value of 4111111111111111.
	specify a value of "4111111111111111".
	specify a value of 4111111111111111.

Parameter tables

If you list parameters in a table and want to mark if fields are required or not: add a center-aligned Required column and enter a checkmark if the field is required. If a field is optional, leave the Required column empty.

Parameter name	Type	Required	Description
city	String		The name of the city.
stateOrProvince	String		State or province codes as defined in ISO 3166-2. Required for the US and Canada. For example, CA in US or ON for Canada.

Referring to a UI

UI elements

Use bold text when referring to a UI element.

Correct	Incorrect
Select Save.	Click "Save".
	Click Save.

User input

Use bold text when describing user-entered input.

Correct	Incorrect
and enter your website URL followed by /adyen/process/json.	and enter your website URL followed by "/adyen/process/json".
	and enter your website URL followed by /adyen/process/json.

Navigating the UI

When you describe navigating to a location in the UI, separate the path items with a >. Use this only when the selection method is the same for each item.

Correct	Incorrect
Go to Account > Users.	Go to Account > Users.
	Go to Account > Users.
	Go to Account, Users.

File names

When writing file names, use monospace.

Correct	Incorrect
Download report_name.csv.	Download report_name.csv.

Placeholder text

Placeholder text in code samples

When using placeholder text in code samples, use CAPITALIZATION, and SEPARATE_WORDS_WITH_AN_UNDERSCORE. This helps to differentiate placeholder text from legitimate parameters or values that developers can use in their code.

// Correct
"merchantAccount": "YOUR_MERCHANT_ACCOUNT",

// Incorrect
// "merchantAccount": "Your Merchant Account",
// "merchantAccount": "YOURMERCHANTACCOUNT"

Web Service user accounts

When referring to Web Service (WS) user accounts, use ws@Company.[YourCompanyAccount].

Correct	Incorrect
and select ws@Company.[YourCompanyAccount].	and select ws@Company.[YourCompanyAccount].
	and select ws@Company.YourCompanyAccount.
	and select ws@Company.TestCompany.

Code samples

JSON

• Formatting: use https://jsonformatter.curiousconcept.com/
• Data types: use the list from http://www.tutorialspoint.com/json/json_data_types.htm

SOAP

• Formatting: use http://www.freeformatter.com/xml-formatter.html
• Try to remove duplicated namespaces and move their declaration to the upper level. Consider using default namespaces, when appropriate.

HTML

• Formatting, use either:
• http://www.w3schools.com/html/html5_syntax.asp
• https://google.github.io/styleguide/htmlcssguide.xml

Links

To write link text, use descriptive phrases that provide context for the material that you are linking to.

Do not use empty words like "this" or "here" as the link text.

When possible, use words from the sentence as the link text instead of adding a phrase like “For more information, see...” or “To learn more, see...”.

You can also capture payments in your Customer Area.
You can capture payments in your Customer Area here.
You can also capture payments in your Customer Area. For more information, refer to Manage payments.

Page Templates

As a best practice, following a structured page format ensures that your content is easily understood by LLMs and users alike.

• The Intro, Requirements, and Exit blocks are REQUIRED.

  All other blocks are optional.

• After the Intro and the Requirements, the order of content type blocks is usually from high-level information to more and more detailed content. For example:

  Background info -> Process overview mentioning some tasks -> The actual task instructions -> Additional details.

  You can use this progression from high-level to detailed content as a guideline. But note that sometimes you need to go back to a higher level of information: after the Tasks, you may need to describe another Concept. For example, to tell a story in a logical order, or to not front-load the readers with information they only need to have after having completed the Tasks.

• It is possible that, to be able to efficiently write Concept type content, you need to switch the order of a Concept block followed by a Process block. An example is card acquisition where the use cases in the Concept block were easier to explain by first presenting the Process block ("How it works").

• The mini-TOC, "On this page", is an important help for readers to get an overview; to quickly navigate to the section that interests them; and to follow the train of thought. The mini-TOC only shows H2 headings (##). Therefore, all blocks that are important for the overview/navigation/train of thought should be H2 headings.

Review our guides within our documentation to see our style in practice: