Business Onboarding

Overview

Onboarding enrolls a business into your program so it can accept card payments, move money, or affiliate with your other businesses.

Onboarding is two mutations, called in order, plus program-level setup that Highnote completes with you before you start:

1. createBusiness records the legal business entity.
2. onboardBusiness enrolls that business into your program.

onboardBusiness is one mutation with three types defined by onboarding member, of which you choose one:

Type	onboarding member	Enrolls the business to ...
Acquiring	merchant	Accept card payments
Money movement	moneyMovement	Move money over payment rails
Independent Sales Organization	iso	Affiliate with other businesses in your program

Not for card issuing

createBusiness and onboardBusiness work only with acquiring and money movement products. To onboard account holders for card issuing, see Onboard an Account.

Program setup

Highnote sets up your program with you before you onboard your first business. During setup, Highnote:

• Configures your application steps. Every onboarding application runs the verification steps configured for your program — identity verification (KYC/KYB), terminated-merchant screening, and underwriting review. Which steps apply depends on the configuration set up for your program.
• Provisions your products. Highnote sets up the products for your program and provides the productId values your integration passes.
• Pricing. onboardBusiness requires a pricingPlanId, so pricing is in place before you onboard your first business. For the acquiring type, Merchant Pricing covers creating, simulating, and publishing a pricing plan; for money movement, your Highnote implementation team provides the pricing ID.

Your Highnote implementation team provides the IDs your integration needs.

How onboarding works

Program setup comes first. These three steps are your integration:

1. Create the business. createBusiness records the legal business entity and returns its ID.
2. Onboard the business. onboardBusiness creates and returns a ProductApplication, which Highnote shepherds toward approval by running your program's application steps. Once approved, Highnote provisions each capability the business requested — setting up settlement, registering with the card networks, and configuring it in the Highnote system. Provisioning steps and timelines vary by capability.
3. Track status and start transacting. Follow the application until the business is ready, then start transacting.

Step 1. Create the business

Use createBusiness to record the legal business entity. This captures the business profile and the people associated with the business.

Select these two fields in the response; each carries an ID needed in Step 2:

• id: The new business's ID. Pass it to Step 2 as businessId.
• businessPersons { id isPrimary }: The people on the business. The person whose isPrimary is true is the primary authorized person; pass their id to Step 2 as consent.primaryAuthorizedPersonId.

mutation CreateBusiness($input: CreateBusinessInput!) {
  createBusiness(input: $input) {
    ... on Business {
      id
      businessProfile {
        name {
          legalBusinessName
          doingBusinessAsName
        }
        externalId
        businessPersons {
          id
          isPrimary
        }
      }
    }
    ... on UserError {
      errors {
        code
        description
        errorPath
      }
    }
    ... on AccessDeniedError {
      message
    }
  }
}

{
  "input": {
    "businessProfile": {
      "name": {
        "legalBusinessName": "<LEGAL_BUSINESS_NAME>",
        "doingBusinessAsName": "<DOING_BUSINESS_AS_NAME>"
      },
      "businessType": "LLC",
      "industryType": "RETAIL_OUTLET_SERVICES",
      "addresses": [
        {
          "addressType": "LEGAL",
          "streetAddress": "<STREET_ADDRESS>",
          "locality": "<CITY>",
          "region": "<REGION>",
          "postalCode": "<POSTAL_CODE>",
          "countryCodeAlpha3": "USA"
        }
      ],
      "jurisdiction": {
        "countryOfIncorporation": "USA",
        "regionOfIncorporation": "US-CA"
      },
      "taxIdentifier": {
        "taxIdentificationNumberType": "EMPLOYER_IDENTIFICATION_NUMBER",
        "number": "<TAX_ID_NUMBER>",
        "countryCodeAlpha3": "USA"
      },
      "customerSupport": {
        "phone": {
          "number": "<PHONE_NUMBER>",
          "countryCode": "1",
          "label": "WORK"
        },
        "email": "<SUPPORT_EMAIL>"
      }
    },
    "businessPersons": [
      {
        "name": { "givenName": "<GIVEN_NAME>", "familyName": "<FAMILY_NAME>" },
        "dateOfBirth": "<DATE_OF_BIRTH>",
        "email": "<PERSON_EMAIL>",
        "phoneNumbers": [
          { "number": "<PHONE_NUMBER>", "countryCode": "1", "label": "WORK" }
        ],
        "homeAddress": {
          "streetAddress": "<STREET_ADDRESS>",
          "locality": "<CITY>",
          "region": "<REGION>",
          "postalCode": "<POSTAL_CODE>",
          "countryCodeAlpha3": "USA"
        },
        "identificationDocument": {
          "socialSecurityNumber": {
            "taxIdentificationNumberType": "SOCIAL_SECURITY_NUMBER",
            "number": "<SSN>",
            "countryCodeAlpha3": "USA"
          }
        },
        "isPrimaryApplicant": true,
        "roles": ["CONTROL_PRONG", "ULTIMATE_BENEFICIAL_OWNER", "GUARANTOR"],
        "percentageOwnership": 100
      }
    ],
    "externalId": "<YOUR_EXTERNAL_ID>"
  }
}

Step 2. Onboard the business

Use onboardBusiness to enable capabilities for the business within your program. It returns a ProductApplication.

Set exactly one member of the onboarding field — omitting it or supplying more than one throws an error. Each member nests its configuration the same way, for example "onboarding": { "merchant": { ... } }:

• merchant: Onboard for acquiring
• moneyMovement: Onboard for money movement
• iso: Contact your Highnote representative.

All onboarding member types share the same mutation and top-level inputs. All three are required:

• businessId: The Business.id returned by createBusiness in Step 1.
• pricingPlanId: The ID of the pricing plan in place for your program. A business cannot be onboarded without one. See Program setup.
• consent: The primary authorized person's agreement to the terms — their ID from Step 1, a timestamp, and the IP address the consent was given from.

Amounts are integers in minor units, e.g., $50.00 is 5000.

mutation OnboardBusiness($input: OnboardBusinessInput!) {
  onboardBusiness(input: $input) {
    __typename
    ... on ProductApplication {
      id
      applicationState {
        status
      }
      business {
        id
      }
      product {
        ... on CardProduct {
          id
          name
        }
      }
      createdAt
      updatedAt
    }
    ... on UserError {
      errors {
        code
        description
        errorPath
      }
    }
    ... on AccessDeniedError {
      message
    }
  }
}

Onboard for acquiring

Supply onboarding.merchant to enroll the business to accept card payments.

Required fields

• productId: The product to onboard the business to, from program setup.
• processingCapabilities: The networks, payment methods, merchant categories, and transaction types the business may process. Each entry takes exactly one of permittedMerchantCategoryCode or permittedMerchantCategoryValues. The schema accepts an application without this field, but nothing provisions and you cannot add capabilities afterward.
• businessProcessingAttributes: The business's reported operating details and processing volumes. These must sum to 100:
  • cardPresentSalesPercentage + cardNotPresentSalesPercentage
  • businessSalesPercentage + consumerSalesPercentage + governmentSalesPercentage

Optional fields

• financialReserves: Reserve requirements withheld from the business's transactions.
  • reserveCollectionMethod selects which value applies: PERCENTAGE or FIXED_AMOUNT. PERCENTAGE uses percentagePerTransaction in basis points (so 200 means 2%), and FIXED_AMOUNT uses amountPerTransaction. The schema requires both on every reserve, even though only the one matching your collection method applies.
  • An optional thresholdAmount caps the total collected.

{
  "input": {
    "businessId": "<BUSINESS_ID>",
    "pricingPlanId": "<PRICING_PLAN_ID>",
    "consent": {
      "consentTimestamp": "<CONSENT_TIMESTAMP>",
      "consentIpAddress": { "v4": "<IP_ADDRESS>" },
      "primaryAuthorizedPersonId": "<AUTHORIZED_PERSON_ID>"
    },
    "onboarding": {
      "merchant": {
        "productId": "<ACQUIRING_CARD_PRODUCT_ID>",
        "processingCapabilities": [
          {
            "permittedProcessingNetwork": "VISA",
            "permittedPaymentMethod": "CARD",
            "permittedMerchantCategoryCode": "5999",
            "permittedTransactionTypes": ["GOODS_AND_SERVICES", "RETURNS"],
            "acquiringProviderType": "CRB",
            "merchantDescriptor": "<MERCHANT_DESCRIPTOR>"
          },
          {
            "permittedProcessingNetwork": "MASTERCARD",
            "permittedPaymentMethod": "CARD",
            "permittedMerchantCategoryCode": "5999",
            "permittedTransactionTypes": ["GOODS_AND_SERVICES", "RETURNS"],
            "acquiringProviderType": "CRB",
            "merchantDescriptor": "<MERCHANT_DESCRIPTOR>"
          }
        ],
        "financialReserves": [
          {
            "reserveType": "RISK",
            "reserveCollectionMethod": "PERCENTAGE",
            "percentagePerTransaction": 200,
            "amountPerTransaction": { "value": 20, "currencyCode": "USD" },
            "thresholdAmount": { "value": 1000000, "currencyCode": "USD" }
          }
        ],
        "businessProcessingAttributes": {
          "annualVolume": { "value": 50000000, "currencyCode": "USD" },
          "averageTicket": { "value": 5000, "currencyCode": "USD" },
          "largestTicket": { "value": 100000, "currencyCode": "USD" },
          "cardPresentSalesPercentage": 60,
          "cardNotPresentSalesPercentage": 40,
          "businessSalesPercentage": 50,
          "consumerSalesPercentage": 40,
          "governmentSalesPercentage": 10
        }
      }
    }
  }
}

Onboard for money movement

Supply onboarding.moneyMovement to enroll the business for money movement.

Required fields

• productId: The product to onboard the business to, from program setup.

Optional fields

• moneyMovementCapabilities: The rails to enable — ACH, US_RTP, FED_NOW, VISA_AFT, VISA_OCT, MASTERCARD_AFT, or MASTERCARD_OCT. The card-network rails (VISA_AFT, VISA_OCT, MASTERCARD_AFT, MASTERCARD_OCT) provision acquiring capabilities for the business. ACH and US_RTP are currently enabled at the product level, so listing them takes no per-business action.
• moneyMovementProcessingAttributes: The business's money movement operating details and licensing, used during underwriting. If you supply it, its yes/no fields and the three description fields are required.
• financialReserves: Same as for acquiring.

Conditional fields

• regulatedEntityDetails is required when isRegulatedEntity is true.
• previousMoneyMovementProcessors is required when hasPreviouslyProcessedTransfers is true.
• otherMoneyMovementLicenseDetails is required when moneyMovementLicenses contains OTHER.

{
  "input": {
    "businessId": "<BUSINESS_ID>",
    "pricingPlanId": "<PRICING_PLAN_ID>",
    "consent": {
      "consentTimestamp": "<CONSENT_TIMESTAMP>",
      "consentIpAddress": { "v4": "<IP_ADDRESS>" },
      "primaryAuthorizedPersonId": "<AUTHORIZED_PERSON_ID>"
    },
    "onboarding": {
      "moneyMovement": {
        "productId": "<MONEY_MOVEMENT_PRODUCT_ID>",
        "moneyMovementCapabilities": ["ACH", "US_RTP"],
        "moneyMovementProcessingAttributes": {
          "isRegulatedEntity": true,
          "regulatedEntityDetails": "Licensed as a Money Transmitter in all required states under NMLS ID 123456.",
          "moneyMovementLicenses": ["MONEY_TRANSMITTER_LICENSE"],
          "hasAmlPolicy": true,
          "hasPreviouslyProcessedTransfers": true,
          "previousMoneyMovementProcessors": ["<PREVIOUS_PROCESSOR>"],
          "hasBeenTerminatedByPreviousProcessor": false,
          "hasPreviousBankruptcy": false,
          "descriptionOfCustomers": "Small and medium-sized businesses in the retail and e-commerce sectors across the United States.",
          "descriptionOfFunding": "ACH pull from a prefunded operating account held at an FDIC-insured bank.",
          "descriptionOfReceivingAccounts": "Consumer checking and business operating accounts at US financial institutions.",
          "annualVolumeEstimates": [
            {
              "year": 1,
              "estimatedVolume": { "value": 500000000, "currencyCode": "USD" },
              "estimatedTransactionCount": 50000
            },
            {
              "year": 2,
              "estimatedVolume": { "value": 1250000000, "currencyCode": "USD" },
              "estimatedTransactionCount": 125000
            }
          ]
        }
      }
    }
  }
}

Results

• A valid application returns a ProductApplication. Step 3 shows how to track it.
• An invalid application returns a UserError synchronously, e.g., a missing required field. errorPath is an array of path segments beginning with the onboarding member you supplied, so a bad merchant field reports as ["merchant", "<field>"].

A call without access returns an AccessDeniedError. Access comes with program setup.

Step 3. Track status and start transacting

Approval and provisioning happen after the mutation returns, so track the application until the business is ready.

Listen for application events

Highnote publishes a notification event at each step of the application phase, so a webhook subscription can drive your integration instead of polling:

Event	Meaning
PRODUCT_APPLICATION_PENDING	The application is being processed.
PRODUCT_APPLICATION_IN_REVIEW	The application requires additional review.
PRODUCT_APPLICATION_DOCUMENT_UPLOAD_REQUESTED	Document upload sessions were requested for the application.
PRODUCT_APPLICATION_APPROVED	The application is approved; capability provisioning begins.
PRODUCT_APPLICATION_DENIED	The application is denied.
PRODUCT_APPLICATION_CLOSED	The application is closed.

Provisioning follows approval and reports through each capability's status rather than through events, so after PRODUCT_APPLICATION_APPROVED switch to the queries below.

Track acquiring status

The application's applicationState.status reports the application overall, and each requested capability reports its own provisioning status:

Capability status	Meaning
PENDING	The capability is being provisioned.
ACTIVE	The capability is provisioned; the business can process on that network.
REJECTED	The capability was not approved and will not become active.
DEACTIVATED	A previously active capability was turned off; it no longer processes.

Check capability status by querying the applications through the Business you created in Step 1. The root productApplications query takes no filter, so reading through the Business is how you scope the result to one business.

query BusinessProductApplications($id: ID!, $first: Int) {
  node(id: $id) {
    ... on Business {
      id
      businessServices {
        merchantDetails {
          productApplications(first: $first) {
            ... on ProductApplicationConnection {
              pageInfo {
                hasNextPage
                endCursor
              }
              edges {
                node {
                  id
                  applicationState {
                    status
                  }
                  contract {
                    processingCapabilities {
                      ... on CardProcessingCapability {
                        permittedProcessingNetwork
                        permittedTransactionTypes
                        status
                        merchantDescriptor
                      }
                    }
                  }
                }
              }
            }
            ... on UserError {
              errors {
                code
                description
                errorPath
              }
            }
          }
        }
      }
      services(first: $first) {
        edges {
          node {
            ... on Merchant {
              id
              merchantAcceptors(first: 20) {
                edges {
                  node {
                    id
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

{
  "id": "<BUSINESS_ID>",
  "first": 20
}

The services selection returns the business's Merchant. Its id is the <MERCHANT_ID> used below, and its MerchantAcceptor IDs (prefix acqma_) are what you reference when you accept payments once capabilities are ACTIVE.

If you already have the merchant's ID, you can query the acceptors directly. The merchant's status reports the merchant itself — ACTIVE means it can process transactions:

query MerchantAcceptors($id: ID!) {
  node(id: $id) {
    ... on Merchant {
      id
      status
      merchantAcceptors(first: 20) {
        pageInfo {
          hasNextPage
          endCursor
        }
        edges {
          node {
            id
          }
        }
      }
    }
  }
}

{
  "id": "<MERCHANT_ID>"
}

Track money movement status

Money movement does not use merchant acceptors, and how you track readiness depends on the rails you requested:

• Card-network rails (VISA_AFT, VISA_OCT, MASTERCARD_AFT, MASTERCARD_OCT) move money to and from cards, so Highnote provisions them as acquiring capabilities for the business. Track them with the acquiring query above — the same capabilities, the same PENDING to ACTIVE lifecycle.
• Bank rails (ACH, US_RTP) are currently enabled at the product level rather than per business, so there is no per-business status to query. Highnote confirms with you when the business is ready to transact.