API Boarding Guide

Start Here

If a partner is building API boarding for the first time, they do not need to read every detail in order. The shortest path is: collect the business, collect the principals, collect the payout bank account, capture Payrix terms evidence, then validate that all of those pieces agree with one another.

What you need for a first working board

Partner API key and login credentials: The partner needs working API access plus the login payload that creates the merchant-facing user record and ties the board to the correct partner context.
Legal business profile and contact information: This is the core business identity, including legal business name, tax ID, business type, address, phone, email, and website.
Merchant processing profile: This is the card-processing setup the underwriter evaluates, including mcc, dba, environment, projected volume, average ticket, and related business activity details.
At least one responsible owner or principal: The board needs at least one real person tied to the business with identifying details such as name, date of birth, SSN, title, ownership, and significant responsibility.
One valid primary payout account: The merchant needs at least one usable settlement account with the correct account number, routing number, method/type mapping, and primary-account flag.
Terms, attestation, acceptance timestamp, and IP evidence: The board must include Payrix terms acceptance evidence, typically through tcVersion, tcDate, tcIp, and merchant tcAttestation.

What usually causes confusion

API required fields: Fields the model or endpoint directly validates as required in the request shape.
Risk and boarding required fields: Values that may not look strictly required in raw API docs, but are still needed in practice to avoid manual review, boarding stalls, or follow-up.
Ownership and responsibility rules for multiple principals: When one owner is not enough, the payload must show the real control structure, including ownership percentages and at least one person with significant responsibility.
Bank account method/type mapping: Partners often know the business meaning, such as checking, savings, personal, or business, but still need to map that correctly into the Payrix account method/type fields.
Form fields versus backend-only fields: Some data should be collected directly from the merchant in the onboarding experience, while other values are derived, defaulted, or inserted only in backend payload construction.
Separate Payrix terms acknowledgement versus partner terms: Agreeing to a partner's general terms is not the same as capturing the distinct Payrix terms acceptance evidence required for boarding.

Boarding Flow

A clean onboarding request usually follows this order: create the login, create the entity and merchant record, attach at least one bank account, then provide ownership and responsibility details through members. Most boarding failures happen because one of those objects is incomplete or because the values are internally inconsistent.

1

Create the login and merchant together when possible. Using /logins with nested entities is a good fit for guided API boarding because the full business profile is captured in one request.

2

Collect legal business data first. Legal name, tax identifiers, business address, business contact details, and business type should be validated before merchant-specific settings like MCC or environment are assigned.

3

Confirm ownership and responsibility coverage. At least one member with significant responsibility is generally expected, and ownership details must reflect the real ownership structure.

4

Validate banking before submit. Bank-account payloads tend to fail due to routing number, account number, ownership mismatch, or unsupported account method values.

How to Read Field Requirements

Not every field belongs in the same bucket. Some values are always required for a viable board, some are optional enrichment, and some become mandatory only when another choice makes them relevant.

Required

The request is usually not viable without this data for the object being created.

Optional

Helpful or commonly populated, but not generally the first reason a board fails.

Conditional

Becomes necessary when a business model, environment, or onboarding path makes it relevant.

Important: “Optional” does not always mean “should be omitted.” Many optional fields are still beneficial because they reduce underwriting follow-up, improve merchant setup accuracy, or help when partners later automate updates and reporting.

API Documented Field Matrix

This section is no longer limited to the minimum required payload. It is a broader boarding field matrix so partners can see which documented fields are required for boarding, which are risk-required, which are optional, and which are conditional based on program or merchant type.

Path note: the matrix starts with the /logins path because that is a common guided onboarding flow, but a merchant account can also be created without a unique merchant login by using a direct entity or merchant creation path. In that case, the merchant will use the login associated with the API key used for the request unless a separate login is later created and associated.

Object	JSON field	Field type	Example	Status	Why it matters	Conditional notes
`/logins`	`first`	`string`	`John`	Required	Merchant first name for the login profile.	Should belong to the actual merchant user or merchant operator being boarded.
`/logins`	`last`	`string`	`Doe`	Required	Merchant last name for the login profile.	Should align with the merchant user account being created.
`/logins`	`email`	`email string`	`john@merchant.com`	Required	Merchant's email address.	Should be unique and monitored.
`/logins`	`username`	`string`	`acmeMerchant`	Required	Merchant username for the login record.	Should be unique and usable after boarding.
`/logins`	`password`	`string`	`Welcome01!`	Required	Initial password for the login.	Should satisfy your onboarding security rules.
`entities[0]`	`type`	`integer`	`1`	Required	Entity or business type.	Drives downstream ownership and risk expectations.
`entities[0]`	`country`	`string`	`USA`	Required	Country of the business.	Should match the legal and banking footprint.
`entities[0]`	`name`	`string`	`Acme Services LLC`	Required	Legal business name.	Should match tax and bank records.
`entities[0]`	`globalBusinessId`	`string`	`111000111`	Required	Business identifier used for identity/tax context.	Use the correct identifier for the boarded entity.
`entities[0]`	`website`	`URL string`	`https://acme.com`	Required	Business website.	Must align with MCC, environment, and business activity.
`entities[0]`	`email`	`email string`	`support@acme.com`	Required	Business email contact.	Should be a monitored business address.
`entities[0]`	`phone`	`string`	`3145551212`	Required	Business phone number.	Use 10 digits only and no leading `1`.
`entities[0]`	`address1`	`string`	`123 Main St`	Required	Primary business street address.	PO Boxes should not be accepted for onboarding.
`entities[0]`	`address2`	`string`	`Suite 200`	Optional	Secondary business address line.	Use when the merchant has a suite, floor, or unit number.
`entities[0]`	`city`	`string`	`St. Louis`	Required	Business city.	Should match the business address and state/ZIP.
`entities[0]`	`state`	`string`	`MO`	Required	Business state or region.	Should be valid for the business address.
`entities[0]`	`zip`	`string`	`63101`	Required	Business postal code.	Should match city/state and not be a PO Box substitute.
`entities[0]`	`industry`	`string`	`Online Retail`	Required	Business industry description.	Should support the chosen MCC and processing environment.
`entities[0]`	`currency`	`string`	`USD`	Required	Business settlement currency.	Should match the boarded program.
`entities[0]`	`locations`	`integer`	`1`	Required	Number of locations.	Risk expects this to be present for boarding.
`entities[0]`	`ein`	`string`	`111000111`	Required	Tax ID / EIN.	Should align with the legal business name.
`entities[0]`	`tcVersion`	`string`	`072023PAYRIXSUBMERCH`	Required	Terms version accepted by the merchant.	Required by risk even if some API docs appear looser.
`entities[0]`	`tcDate`	`datetime string`	`2026-03-20 14:29:38`	Required	Terms acceptance timestamp.	Should reflect the actual acceptance event.
`entities[0]`	`tcIp`	`IP string`	`209.59.249.33`	Required	IP associated with the terms acceptance event.	Required by risk for boarding evidence.
`entities[0]`	`tcAcceptDate`	`null or date string`	`null`	Optional	Additional acceptance date field when your flow captures it separately.	Use only when your implementation stores this distinctly from `tcDate`.
`entities[0]`	`tcAcceptIp`	`IP string`	`209.59.249.33`	Conditional	Additional acceptance IP field when your flow captures it separately.	Should align with the same acceptance event as the other T&C fields.
`entities[0]`	`public`	`integer`	`0`	Conditional	Indicates whether the business is public.	Conditionally required when `entity.type` is `NONPROFIT (5)` or `GOV (6)`; otherwise it will be `0`.
`accounts[0]`	`primary`	`integer`	`1`	Required	Marks the payout account as primary.	If there is one account, it should be primary.
`accounts[0]`	`currency`	`string`	`USD`	Required	Currency for the payout account.	Should align with settlement expectations.
`account`	`method`	`string or integer code`	`8`	Required	Mapped account method/type value.	Must match the intended bank account type mapping.
`account`	`number`	`string`	`456123789`	Required	Bank account number.	Should be validated and owned by the merchant or valid related owner.
`account`	`routing`	`string`	`021000021`	Required	Bank routing number.	Should be validated before submit.
`merchant`	`status`	`integer`	`1`	Required	Merchant onboarding status field.	Should be intentionally set or mapped on the backend.
`merchant`	`mcc`	`string`	`7372`	Required	Merchant category code.	Must match actual merchant activity.
`merchant`	`environment`	`string`	`ecommerce`	Required	Processing environment.	Should match website, products, and transaction flow.
`merchant`	`dba`	`string`	`Acme Services`	Required	Merchant DBA / statement-facing brand.	Should align with statement descriptor and site branding.
`merchant`	`annualCCSales`	`integer`	`550000000`	Required	Expected annual card sales.	Required by risk and should be realistic.
`merchant`	`established`	`date string`	`20181015`	Required	Business established date.	Required for boarding and should reflect the real business start date.
`merchant`	`avgTicket`	`integer`	`150000`	Required	Expected average ticket.	Required by risk and should fit the business model.
`merchant`	`tcAttestation`	`integer`	`1`	Required	Merchant attestation field required by risk.	Should be deliberately mapped and tied to the merchant's acknowledgement flow.
`merchant`	`visaDisclosure`	`integer`	`1`	Conditional	Network disclosure field.	Use only when required by the boarded program.
`merchant`	`new`	`integer`	`0`	Conditional	Indicates whether the merchant is net-new to processing payments.	Only set this to `1` if the merchant is truly net-new to payment processing.
`members[0]`	`title`	`string`	`CEO`	Required	Principal's business title.	Clarifies the person's role and authority.
`members[0]`	`first`	`string`	`Jane`	Required	Principal first name.	Should match identity records.
`members[0]`	`middle`	`string`	`A`	Optional	Principal middle name or initial.	Use when the partner collects it and identity records support it.
`members[0]`	`last`	`string`	`Doe`	Required	Principal last name.	Should match identity records.
`members[0]`	`email`	`email string`	`jane@acme.com`	Required	Principal contact email required for risk boarding.	Should be a real monitored email for the principal being collected.
`members[0]`	`phone`	`string`	`3145551212`	Required	Principal phone number.	Use 10 digits only and no leading `1`.
`members[0]`	`dob`	`date string`	`19900612`	Required	Principal date of birth.	Needed for identity review.
`members[0]`	`ssn`	`string`	`112233333`	Required	Principal SSN.	Needed for identity verification.
`members[0]`	`significantResponsibility`	`integer`	`1`	Required	Identifies a person with significant responsibility.	At least one principal should satisfy this role.
`members[0]`	`address1`	`string`	`123 Main St`	Required	Principal street address.	PO Boxes should not be accepted.
`members[0]`	`address2`	`string`	`Apt 4B`	Optional	Secondary principal address line.	Use when the principal has a unit, suite, or apartment number.
`members[0]`	`city`	`string`	`St. Louis`	Required	Principal city.	Should match the rest of the address.
`members[0]`	`state`	`string`	`MO`	Required	Principal state.	Should match the rest of the address.
`members[0]`	`zip`	`string`	`63101`	Required	Principal postal code.	Should match city/state.
`members[0]`	`country`	`string`	`USA`	Required	Principal country.	Should align with identity and address records.
`members[0]`	`primary`	`integer`	`1`	Required	Marks the primary principal/contact for risk boarding.	Should be set intentionally, especially when multiple principals are present.
`members[0]`	`ownership`	`integer`	`10000`	Required	Ownership percentage value.	Needed when ownership thresholds drive beneficial-owner collection.
`members[0]`	`timezone`	`string`	`cst`	Optional	Principal timezone.	Helpful operationally, but not required for risk boarding.

Validation Rules

These are the kinds of field-level validation rules that matter during actual boarding, even when the raw API shape alone does not make them obvious. This is the section partners should read when they are building frontend validation, backend validation, or pre-submit QA checks.

Entity Model Validations from Code

type: required and must be one of the supported entity types such as SOLE, CORP, LLC, PARTNER, ASSOCIATION, NONPROFIT, GOV, CCORP, or SCORP.
name: required, stripped of HTML, and limited to 1 to 100 characters.
displayName: optional, stripped of HTML, and limited to 1 to 1000 characters when present.
address1: required, stripped of HTML, and limited to 1 to 500 characters.
address2: optional, stripped of HTML, and limited to 0 to 500 characters.
city: required, stripped of HTML, and limited to 1 to 500 characters.
state: required. For USA it must be in the supported US state list. For CAN it must be in the supported Canadian province list. Otherwise it must be 2 to 100 characters and non-HTML.
zip: required, must be 1 to 20 characters, and may contain only alphanumeric characters, spaces, and hyphens.
country: required and must be a supported country, currently USA or CAN.
timezone: the entity model treats this as required and it must be one of the supported timezone values. Older integer-based timezone values are also converted internally.
phone: required numeric value with length between 5 and 15.
customerPhone and fax: optional numeric values with length between 5 and 15 when present.
email: required, must be a valid email address, and must be 1 to 100 characters.
website: optional in the raw entity model, but when present it must be a valid URL and no longer than 500 characters.
locations: required numeric range between 1 and 1000000.
currency: required and must be in the supported currency domain.
industry: optional in the raw entity model, stripped of HTML, and limited to 0 to 1000 characters.
custom: optional, stripped of HTML, and limited to 0 to 1000 characters.
payoutSecondaryDescriptor: optional, stripped of HTML, and limited to 0 to 15 characters.
clientIp and tcAcceptIp: optional, but when present they must be valid IPv4 or IPv6 addresses.
tcVersion: optional in the raw model, but when present it must be alphanumeric or periods only and no longer than 20 characters. In the boarding flow shown on this page, this is the terms-version field partners should deliberately map.
tcDate and tcIp: these are the main terms-acceptance timestamp and IP evidence fields used throughout this guide's boarding examples and checklist.
tcAcceptDate and tcAcceptIp: optional supplemental acceptance fields. Use them only when your implementation stores acceptance evidence separately from tcDate and tcIp.
public: required and validated by entity type. SOLE forces 0, public entity types such as GOV (6) and NONPROFIT (5) force 1, and all others must be boolean-style values.
ein and globalBusinessId: validation changes by type and country. For many non-sole US and Canadian entity types they are required and must be 9 characters. Sole proprietors may be allowed to omit them depending on country and flow.
einType and globalBusinessType: optional, but when present must be in the allowed domain for the selected country.
irsFilingName: optional, limited to 1 to 40 characters, and restricted to the allowed character set defined in the model.

Login Model Validations from Code

username: required, alphanumeric only, 1 to 50 characters, and unique within the same partition.
password: required, 1 to 100 characters, and also subject to password-strength rules from the login model and partition/division settings.
first: required, stripped of HTML, and limited to 1 to 100 characters.
middle: optional, stripped of HTML, and limited to 0 to 100 characters.
last: required, stripped of HTML, and limited to 1 to 100 characters.
email: required, must be a valid email address, and must be between 0 and 100 characters in the model constraint.
allowedResources: if you use API-driven access templates, this is the field that carries the allowed resource/action JSON. It must be valid resource JSON and can only grant access the acting login is already allowed to manage.

Accounts Model Validations from Code

entity and account: both are required relations. The nested account object must resolve to a valid payment record.
name and description: optional, stripped of HTML, and limited to 0 to 100 characters each.
primary: required boolean-style field. If primary = 1, the combination of primary, entity, and type must be unique.
type: required and must be one of all, credit, or debit.
status: required and must be one of the supported account states such as NOTREADY, READY, CHALLENGED, VERIFIED, or MANUAL.
currency: required and must be a supported currency. If not explicitly passed, the model will try to inherit it from the related entity.
expiration: optional, but if present it must be a future date in MMYY format and only applies to Visa or Mastercard account methods.
publicToken and plaidAccountId: optional, stripped of HTML, and limited to 0 to 100 characters.
entity plus account: the same underlying account cannot be duplicated for the same entity.
entity plus plaidAccountId: must be unique when a Plaid account identifier is present.
platform, accountToken, and publicToken: if any of these integration fields are provided, the rest of the required token context must also be present or account-token processing fails.
platform = PLAID: at least one of accountToken or publicToken must be available for processing, otherwise the request fails.
account.method: non-bank payment methods are rejected for bank-account records. Visa and Mastercard methods are only allowed when the account is not primary.
primary with Visa or Mastercard account methods: the model blocks primary card-based payout accounts.
account.routing: if present, it must validate as a routing number, and the routing country must align with the entity currency.
primary changes: blocked while the related entity is in pending risk review, and blocked for boarded merchants when attempting to demote or delete the primary account outside the trusted internal flow.
primary updates: promoting a new primary account automatically unflags the previous primary account of the same type when allowed.
account.number and account.routing: treated as change-restricted fields and used to determine whether the update path is manual or Plaid-driven.

Merchants Model Validations from Code

entity: required relation. The merchant is tightly coupled to a single entity, and the model blocks reuse of the same entity where entity-use rules would be violated.
dba: optional, limited to 0 to 50 characters, and restricted to letters, numbers, spaces, commas, underscores, hyphens, apostrophes, ampersands, and periods.
new: required boolean-style field. It drives several other conditional validations, especially projected versus historical volume fields.
advancedBilling, seasonal, incrementalAuthSupported, visaDisclosure, applePayActive, and passTokenEnabled: optional boolean-style fields validated against the model's boolean domain.
tcAttestation: required boolean-style field and typically expected to be 1 when the merchant has completed the attestation step.
established: optional in the raw model, but when present it must be a past date in YYYYMMDD format.
annualCCSales: when new = 0, it is required, numeric, and must be between 0 and the merchant max sales value. Otherwise it must resolve to 0.
annualCCSaleVolume and annualACHSaleVolume: when new = 1, they may be provided as numeric values between 0 and the merchant max sales value. Otherwise they must be null. The model also blocks setting either one on create.
amexVolume: when new = 0, it must be numeric between 0 and 900000000. Otherwise it must be 0.
avgTicket: required numeric range between 0 and the merchant max sales value.
amex and discover: optional string fields limited to 1 to 15 characters when present.
mcc: validated through effective MCC logic, not just a static enum, so acceptable values depend on the acting login/entity context.
visaMvv: optional, alphanumeric only, 1 to 6 characters, and additionally blocked unless the merchant MCC is in the approved Visa MCC list configured by the system.
disclosureIP: optional valid IPv4 or IPv6 address.
disclosureDate: optional current-or-past date in YYYYMMDD format.
environment: required and must be one of the supported environments such as ecommerce, cardPresent, moto, restaurant, fuel, serviceStation, or supermarket. If not provided on create, the model may derive it from MCC or default to ecommerce.
status: required and must be one of the merchant status codes: 0 = NOTREADY, 1 = READY, 2 = BOARDED, 3 = MANUAL, 4 = CLOSED, 5 = INCOMPLETE, or 6 = PENDING. For vendor/referrer users, these numeric values are usually more useful than the internal constant names.
locationType: optional and must be in the supported merchant-location domain.
percentEcomm, percentKeyed, and percentBusiness: optional numeric ranges from 0 to 100.
totalVolume: optional numeric range from 1 to the max supported dollar value.
saqType: optional and must be one of the supported PCI SAQ types. If set, saqDate becomes required and must be a current-or-past date in YYYYMMDD format. Otherwise saqDate must be null.
qsa: optional, stripped of HTML, and limited to 0 to 500 characters.
chargebackNotificationEmail: optional, but must be a valid email when present.
naics: optional and must be one of the supported NAICS domain values. naicsDescription is optional and limited to 0 to 100 characters; for the “Other Services” bucket the setter prefixes it with Other:.
tmxSessionId: optional, 1 to 128 characters when present, and restricted to alphanumeric characters, hyphens, and underscores.
expressBatchCloseMethod: optional and must be one of the supported Express close methods. expressBatchCloseTime is optional and must be a valid HH:II:SS time when present.
tcVersion: accepted as an extra merchant payload field but synced onto the related entity model rather than living purely as a merchant field.
boarded merchant restrictions: once boarded, fields like visaDisclosure, disclosureIP, disclosureDate, and tcAttestation become restricted unless the actor has elevated boarded-status permissions.
pendingRiskCheck dependency: the model blocks merchant saves while the parent entity is still in pending risk review.

Members Model Validations from Code

merchant, facilitator, and vendor: these parent relations are mutually exclusive. Exactly one parent context is expected for a member record.
primary: required boolean-style field. If primary = 1, it must be unique within the same merchant, facilitator, or vendor context.
title: optional, stripped of HTML, and limited to 0 to 100 characters.
first and last: required, stripped of HTML, and limited to 1 to 100 characters.
middle: optional, stripped of HTML, and limited to 0 to 100 characters.
ssn: optional in the raw model, numeric only, redacted, and must be exactly 9 digits when present.
citizenship: optional and must be one of the supported countries. For some merchant/platform combinations, the model makes this effectively required during save logic.
dob: required, redacted, and must be a past date in YYYYMMDD format.
gender: optional and must be male or female.
dl: optional, redacted, alphanumeric only, and limited to 0 to 15 characters.
dlstate: optional. If country = USA, it must be a supported US state. If country = CAN, it must be a supported Canadian province. Otherwise it must be 2 to 100 characters and non-HTML.
email: required, must be a valid email address, and limited to 0 to 100 characters.
ownership: required numeric range from 0 to 10000.
significantResponsibility and politicallyExposed: required boolean-style fields.
mailingAddress1, mailingAddress2, and mailingCity: optional, stripped of HTML, and limited to 0 to 100 characters.
mailingState: optional. If mailingCountry = USA, it must be a supported US state. If mailingCountry = CAN, it must be a supported Canadian province. Otherwise it must be 2 to 100 characters and non-HTML.
mailingCountry: optional and must be one of the supported countries.
mailingPostalCode: optional, limited to 0 to 20 characters, and restricted to the allowed postal-code character set.
treasuryPrimeRoles: optional, but if present it must be valid JSON containing only supported role values such as signer or control_person.
timezone: required and must be one of the supported entity timezones. If omitted, the model attempts to derive it from state and zip, then falls back to EST.
pendingRiskCheck dependency: the model blocks member saves while the parent entity is in pending risk review.
ownership total: across sibling members under the same merchant, facilitator, or vendor, total ownership cannot exceed 10000.
ownership for government entities: if the parent entity type is GOV, ownership must be 0.
primary and ownership for sole proprietors: if the parent entity type is SOLE, the member must be primary = 1 and ownership = 10000.
citizenship for certain routes: if the merchant is routed through the Wells Fargo boarding path, the model requires citizenship even though the raw field validation marks it optional.
ssn for sole proprietors: when the member is primary and the parent entity is a sole proprietorship, the member SSN is copied onto the entity EIN/business ID path during save.
primary changes on boarded merchants: updating or deleting a primary member is blocked once the related merchant is boarded.

Bank Account Notes

Bank-account onboarding usually deserves its own validation pass. The API shape is small, but errors are common because banking details have less room for interpretation.

Required follow-up for manual bank accounts: if a bank account is manually entered or manually updated, supporting documents should be uploaded after the initial merchant creation flow so underwriting can review and verify the account.

Post-Creation Bank Document Upload Flow

When this applies: use this flow for manually entered or updated bank accounts that need underwriting review.
When it happens: this should occur after the initial merchant creation call, not inside the original merchant/login payload.
Entity reference used by /notes: the entity field on the notes call should be the entityId for the merchant account, not the merchant ID itself.
How to get the entityId: use the entity value returned on the merchant record. In practice, partners usually get this either from the original boarding response that created the merchant or by retrieving the merchant later and reading its entity field.
Step 1: create a review note with POST /notes using that merchant entityId.
Step 2: create one or more document records with POST /noteDocuments using the returned note ID and the required documentType values.
Step 3: upload the actual files with POST /files/noteDocuments/{{noteDocumentsId}} using each created noteDocument ID.
Expected result: the note gives underwriting a shared review record, each noteDocument starts as a created document record, and each uploaded file should move the related noteDocument.status to processed.

Document Type	What it should show	Important constraints
`voidCheck`	A voided check for the payout account.	Must not be a starter check or screenshot.
`bankStatement`	A bank statement showing account and routing numbers.	Should be dated within the last 60 days.
`bankLetter`	A bank letter with bank name, phone, account number, routing number, and business name.	Should clearly tie the account to the boarded business.

RequestExample for POST /notes

{
  "entity": "t1_ent_123abc4d567890efg1h2i34",
  "type": "note",
  "note": "Supporting documents for new bank account"
}

ResponseExample shape from POST /notes

{
  "response": {
    "data": [
      {
        "id": "t1_not_123abc4d567890efg1h2i34",
        "entity": "t1_ent_123abc4d567890efg1h2i34",
        "type": "note",
        "note": "Supporting documents for new bank account"
      }
    ]
  }
}

RequestExample for POST /noteDocuments

{
  "note": "t1_not_123abc4d567890efg1h2i34",
  "documentType": "voidCheck"
}

ResponseExample shape from POST /noteDocuments

{
  "response": {
    "data": [
      {
        "id": "t1_ntd_123abc4d567890efg1h2i34",
        "note": "t1_not_123abc4d567890efg1h2i34",
        "documentType": "voidCheck",
        "status": "created"
      }
    ]
  }
}

RequestExample for POST /files/noteDocuments/{{noteDocumentsId}}

curl -X POST "https://test-api.payrix.com/files/noteDocuments/{{noteDocumentsId}}" \
  -H "Accept: application/json" \
  -H "APIKEY: {apiKey}" \
  -F "name=Voided Bank Check" \
  -F "filename=@VoidedBankCheck.png;type=image/png"

ResponseExample shape from POST /files/noteDocuments/{{noteDocumentsId}}

{
  "response": {
    "data": [
      {
        "id": "t1_ntd_123abc4d567890efg1h2i34",
        "documentType": "voidCheck",
        "name": "VoidedBankCheck.png",
        "type": "png",
        "status": "processed"
      }
    ]
  }
}

Implementation detail: for best results, upload files as PDF, JPG/JPEG, or PNG. Save the note ID returned by POST /notes because you need it when creating document records with POST /noteDocuments. Then save each noteDocument ID returned by POST /noteDocuments because you need that ID for the file upload call to POST /files/noteDocuments/{{noteDocumentsId}}.

Implementation Readiness Checklist

This section turns the boarding guidance into an implementation checklist that can be used during partner onboarding reviews. Open only the section you need. It is especially useful when your team needs to confirm what the partner captures on screen, what is passed on the backend, and which requirements need explicit approval or follow-up.

Business Information

Requirement	Status	Implementation note	Risk / dependency
Legal Business Name (`entities[0].name`)	Required	Should map to the boarded entity legal name, not just the public DBA.	Mismatch between legal name and tax/bank records often causes underwriting follow-up.
Statement Descriptor (`merchant.dba`)	Optional	Should align with how the merchant appears to cardholders.	Descriptors that do not match DBA/brand can create dispute and support risk.
Tax ID Number (`entities[0].ein` / `entities[0].globalBusinessId`)	Required	Should map to EIN or the correct business identifier for the boarded entity.	Tax ID must align with the legal business profile.
Entity Type (`entities[0].type`)	Required	Needed to determine ownership and identity expectations.	Business type affects who must be collected as principals and beneficial owners.
Public (`entities[0].public`)	Conditional	Confirm whether this is collected or defaulted on the backend.	Should be explicitly understood rather than silently assumed.
Website (`entities[0].website`)	Required	Especially important for ecommerce and digital merchants.	Website, MCC, environment, and business description should all align.
Business Email (`entities[0].email`)	Required in practice	Should be a monitored business contact address.	Avoid using placeholder or personal emails unless justified.
Business Address (`entities[0].address1`, `address2`, `city`, `state`, `zip`, `country`)	Required	Capture `address1`, `address2`, `city`, `state`, `zip`, `country`.	Form should explicitly say PO Boxes are not acceptable for onboarding.
Business Phone (`entities[0].phone`)	Required	Enforce 10 digits only with no leading `1`.	Bad normalization here creates avoidable validation issues.
MCC (`merchant.mcc`)	Required	Should reflect the merchant's real business activity.	MCC must align with website, descriptor, environment, and products/services sold.
Payment Parameters - Annual Sales (`merchant.annualCCSales`)	Required	Confirm this is passed in the backend payload.	Unrealistic annual sales values drive manual review.
Payment Parameters - Average Ticket (`merchant.avgTicket`)	Required	Confirm this is passed in the backend payload.	Average ticket should be plausible relative to annual volume and business type.
Boarding Status (`merchant.status`)	Required	Should be set to `1` (`Ready`) during onboarding to help prevent avoidable boarding delays.	If this is omitted or mapped inconsistently, the merchant can stall before downstream boarding begins.
Terms + Conditions Version (`entities[0].tcVersion`)	Required when T&C evidence is collected	Should map to the exact Payrix terms version displayed to the merchant.	Version drift between UI and payload creates audit risk.
Terms + Conditions Acceptance Date / Time (`entities[0].tcDate`)	Required when T&C evidence is collected	Should reflect the actual acceptance event timestamp.	Capture date and acceptance event should remain synchronized with version/IP data.
Merchant IP Address (`entities[0].tcIp`)	Required when acceptance evidence is captured	Should be collected from the onboarding user session.	Static or internal IP placeholders weaken acceptance evidence.
Established Date (`merchant.established`)	Required if boarding to Core	Should be validated as a real business-established date.	Important conditional field for VCORE-style boarding requirements.

Primary Owner and Additional Owners

Requirement	Status	Implementation note	Risk / dependency
First Name / Last Name (`members[0].first`, `members[0].last`)	Required	Collect for the primary owner and any additional qualifying principals.	Name data should match identity records and related ownership details.
DOB (Date of Birth) (`members[0].dob`)	Required	Normalize as a valid date and format consistently before submit.	Used for identity verification and beneficial ownership review.
Social Security Number (`members[0].ssn`)	Required in practice	Should be collected securely and transmitted only where appropriate.	Identity mismatch or formatting issues create immediate friction.
Business Title (`members[0].title`)	Required	Clarifies the person's role in the business.	Important when a signer has significant responsibility but limited ownership.
Ownership Percentage (`members[0].ownership`)	Conditional but usually required	Capture ownership for each relevant principal.	Any principal with 25% or more should be collectable through the form flow.
Owner Email (`members[0].email`)	Strongly recommended	Use a real contactable email for follow-up if needed.	Helpful for identity or underwriting communication.
Significant Responsibility (`members[0].significantResponsibility`)	Required in practice	At least one individual should be marked as having significant responsibility.	Do not rely on ownership alone to satisfy this requirement.
Owner Address (`members[0].address1`, `address2`, `city`, `state`, `zip`, `country`)	Required	Capture full address and display the same “PO Boxes are not acceptable” instruction.	Owner residence and identity details should be internally consistent.
Owner Phone (`members[0].phone`)	Required	Enforce 10 digits only with no leading `1`.	Normalize this the same way as business phone.
Ability to add multiple individuals	Required for a complete onboarding flow	The form should support adding additional principals when another person owns 25% or more.	A single-owner-only UI will not work for many entities.
FinCEN language	Required content	Include the required identity and beneficial ownership disclosure language or approved equivalent.	This is a compliance-facing requirement, not just a UX preference.
Primary Contact (`members[0].primary`)	Required operationally	Allow the partner or merchant to indicate which principal is the primary business contact.	Useful for follow-up, support, and review routing.

Banking Information

Requirement	Status	Implementation note	Risk / dependency
Account Type (`accounts[0].type`)	Required	Should clearly identify business/personal and checking/savings behavior where applicable.	Often combined with account method in the UI.
Account Method (`account.method`)	Required	Confirm the Payrix method code is mapped correctly from the partner experience.	Bad method mapping is a common silent backend issue.
Account Number (`account.number`)	Required	Validate formatting and ownership alignment.	Should be collected securely and never treated as display-only data.
Routing Number (`account.routing`)	Required	Validate format before submit.	Incorrect routing causes payout setup failures quickly.
Primary Account (`accounts[0].primary`)	Required	If there is one account, it must be primary. If there are multiple accounts, exactly one should be primary.	Good place for a frontend or backend validation rule.
Bank Validation	Program dependent but strongly recommended	Implementation should confirm whether Plaid validation is used or a voided-check upload is mandatory.	Partners need a clear fallback when automated validation is unavailable.

Platform Onboarding Requirements

Requirement	Status	Implementation note	Risk / dependency
Cardholder Verification	Required operationally	Implementation should confirm AVS and CVV are prompted where applicable.	Important for fraud controls and merchant processing expectations.
Transaction IP Address	Required operationally	Implementation should confirm transaction IP is passed where relevant.	This is different from merchant onboarding IP but often overlooked in the same implementation review.
Transaction Processing Method	Required operationally	Document whether the merchant will use PayFields, terminals, or direct API processing.	If processing method is API, the platform is required to pass a TMX session ID.
PCI AOC if Processing Method = API	Conditional	Required when the partner touches cardholder data in their own API implementation.	This should not be left ambiguous during partner onboarding.
PCI Compliance - Platform	Conditional	If the partner touches cardholder data, current PCI AOC should be provided.	Compliance requirement depends on how the partner processes payment data.
PCI Compliance - Merchant	Conditional	Implementations should notify the partner when merchant-level PCI status is required.	Especially important for merchants processing 20,000+ Visa/Mastercard or 10,000+ Amex transactions annually.

Payrix Terms Agreement

Requirement	Status	Implementation note	Risk / dependency
Hosted vs partner-hosted Payrix TOS	Required design decision	Implementation must confirm whether the partner links directly to hosted Payrix terms or hosts approved versions in their application.	This affects agreement presentation and evidence capture.
URLs to partner-hosted Payrix TOS and disclosures	Required if partner-hosted	Should include Payrix sub-merchant agreement, direct merchant agreement, Amex requirements, and applicable bank disclosures.	Do not assume one generic terms URL covers all required agreements.
Payrix Terms and Conditions acknowledgement	Required	Should include bank disclosure language and require the user to open and review the Payrix terms before accepting.	Partners may not embed Payrix terms inside their own terms with one shared checkbox.
Attestation Statement	Required	Separate from the T&Cs. Should state that the signer is authorized and the submitted information is true to the best of their knowledge.	This should have its own acknowledgement path, not be buried in generic terms text.

Annotated Example Payload

The sample below is for POST /logins, using a request URL such as https://test-api.payrix.com/logins or https://api.payrix.com/logins. It is useful because it shows the full nested shape in one request, and the callouts under it explain the parts that partners most often need help understanding.

{
  "first": "John",
  "last": "Doe",
  "email": "john.doe@acmeservices.com",
  "username": "acmeservicesMerchant",
  "password": "Welcome01!",
  "entities": [
    {
      "type": 1,
      "country": "USA",
      "name": "Acme Services LLC",
      "globalBusinessId": "111000111",
      "website": "https://acmeservices.com",
      "email": "support@acmeservices.com",
      "phone": "3145551212",
      "address1": "123 Main St",
      "address2": "",
      "city": "St. Louis",
      "state": "MO",
      "zip": "63101",
      "industry": "Software Services",
      "currency": "USD",
      "ein": "111000111",
      "tcVersion": "072023PAYRIXSUBMERCH",
      "tcDate": "2026-03-20 14:29:38",
      "tcIp": "209.59.249.33",
      "tcAcceptDate": null,
      "tcAcceptIp": "209.59.249.33",
      "public": 0,
      "locations": 1,
      "accounts": [
        {
          "primary": "1",
          "currency": "USD",
          "account": {
            "method": "8",
            "number": "456123789",
            "routing": "021000021"
          }
        }
      ],
      "merchant": {
        "status": 1,
        "mcc": "7372",
        "environment": "ecommerce",
        "dba": "Acme Services",
        "annualCCSales": "550000000",
        "established": "20181015",
        "avgTicket": "150000",
        "tcAttestation": 1,
        "new": 0,
        "visaDisclosure": 1,
        "members": [
          {
            "title": "CEO",
            "first": "Jane",
            "middle": "",
            "last": "Doe",
            "email": "jane.doe@acmeservices.com",
            "phone": "3145551313",
            "dob": "19900612",
            "ssn": "112233333",
            "significantResponsibility": 1,
            "address1": "456 Market St",
            "address2": "",
            "city": "St. Louis",
            "state": "MO",
            "zip": "63103",
            "country": "USA",
            "primary": 1,
            "ownership": 10000,
            "timezone": "cst"
          }
        ]
      }
    }
  ]
}

JSON object: top-level request body
Fields: first, last, email, username, password
This is the merchant login object used for the boarded merchant relationship.

JSON object: entities[0]
Fields: type, country, name, globalBusinessId, website, email, phone, address1, address2, city, state, zip, industry, currency, ein, tcVersion, tcDate, tcIp, tcAcceptDate, tcAcceptIp, public, locations
This is the legal business profile. Legal name, tax IDs, business contact values, business address, and business descriptors should all align.

JSON object: entities[0].accounts[0] and entities[0].accounts[0].account
Fields: primary, currency, account.method, account.number, account.routing
This is the payout destination. If the merchant should receive funds after boarding, this block should be validated with the same care as the business identity block.

JSON object: entities[0].merchant
Fields: status, mcc, environment, dba, annualCCSales, established, avgTicket, tcAttestation, new, visaDisclosure
This is where processing-specific context lives, including environment, MCC, DBA, and expected processing volume.

JSON object: entities[0].merchant.members[0]
Fields: title, first, middle, last, email, phone, dob, ssn, significantResponsibility, address1, address2, city, state, zip, country, primary, ownership, timezone
This is where beneficial owner and managing-person data live. If the business has more than one relevant owner, the payload should represent that ownership structure honestly.

Example: Create the merchant and entity without an explicit /logins call

This example is for a direct POST /entities flow, using a request URL such as https://test-api.payrix.com/entities or https://api.payrix.com/entities. If you create the merchant and entity without explicitly creating a login, the system will default the merchant login relationship to the login associated with the API key used for the request.

{
  "type": 1,
  "country": "USA",
  "name": "Acme Services LLC",
  "globalBusinessId": "111000111",
  "website": "https://acmeservices.com",
  "email": "support@acmeservices.com",
  "phone": "3145551212",
  "address1": "123 Main St",
  "address2": "",
  "city": "St. Louis",
  "state": "MO",
  "zip": "63101",
  "industry": "Software Services",
  "currency": "USD",
  "ein": "111000111",
  "tcVersion": "072023PAYRIXSUBMERCH",
  "tcDate": "2026-03-20 14:29:38",
  "tcIp": "209.59.249.33",
  "public": 0,
  "locations": 1,
  "accounts": [
    {
      "primary": "1",
      "currency": "USD",
      "account": {
        "method": "8",
        "number": "456123789",
        "routing": "021000021"
      }
    }
  ],
  "merchant": {
    "status": 1,
    "mcc": "7372",
    "environment": "ecommerce",
    "dba": "Acme Services",
    "annualCCSales": "550000000",
    "established": "20181015",
    "avgTicket": "150000",
    "tcAttestation": 1,
    "new": 0,
    "members": [
      {
        "title": "CEO",
        "first": "Jane",
        "last": "Doe",
        "email": "jane.doe@acmeservices.com",
        "phone": "3145551313",
        "dob": "19900612",
        "ssn": "112233333",
        "significantResponsibility": 1,
        "address1": "456 Market St",
        "city": "St. Louis",
        "state": "MO",
        "zip": "63103",
        "country": "USA",
        "primary": 1,
        "ownership": 10000,
        "timezone": "cst"
      }
    ]
  }
}

Important: this path creates the business objects without an explicit merchant login in the request body. When that happens, the system sets the login relationship to the login associated with the API key used for the request unless your implementation later creates and associates a separate login.

Common Reasons an API Board Fails

These are not just generic validation misses. They are the patterns that most often cause a merchant to stall, move to manual review, or fail boarding even when the payload looks mostly complete at first glance.

Missing responsible member

The business and bank data may be present, but the merchant still does not have a clearly identifiable principal. This usually means the members[0] block is missing, incomplete, or does not show a believable responsible person. Fields like first, last, dob, ssn, primary, ownership, and significantResponsibility need to support the real ownership and control structure of the business.

Website and environment mismatch

The merchant profile tells one story, but the website and business details tell another. A common example is environment = ecommerce while the website, mcc, industry, or dba do not support that setup. Missing websites, inactive sites, placeholder pages, or sites that do not match the products and services in the boarding data frequently trigger review.

Bank details are syntactically present but operationally wrong

The bank block exists, so the request looks complete, but the payout account is still not usable. Typical problems are bad values in account.routing, account.number, account.method, accounts[0].currency, or accounts[0].primary. Failures often happen when the account belongs to the wrong owner, the method or type mapping is wrong, or a manual bank change is submitted without the required supporting documents.

Underwriting values are unrealistic

The individual values may all pass basic validation, but together they do not describe a believable business. Fields such as annualCCSales, avgTicket, established, mcc, environment, and locations need to make sense as one profile. When they do not, underwriting usually slows the board, asks follow-up questions, or rejects the submission.

Official References

These are the docs this page is based on and should remain the source of truth when your partner program, underwriting flow, or bulk process changes.

Worldpay: Onboard merchant tutorial

Payrix: Merchant signup form

Payrix: Onboarding requirements checklist

Worldpay: Add/update bank accounts

Payrix: Merchant bulk upload requirements

Scope note: Field requirements can still vary by boarding program, country, processor, network, or internal underwriting policy. This page is meant to reduce guesswork, not replace the official boarding rules attached to your program.