Migrate from legacy boarding to intelligent boarding

The intelligent boarding API replaces the legacy /Boarding/* endpoints. In legacy boarding, one application object held the business, its owners, its bank accounts, and its services. In intelligent boarding, each of those is its own record, and the application requests services for a business that already exists. Moving an integration to intelligent boarding changes the call sequence, the shape of your data, validation, and how you track an application after you submit it.

Legacy boarding is deprecated and will be sunset in Q2 2027. After that, legacy boarding endpoints will no longer be available, and requests to them may fail. Until then, legacy boarding receives only critical security and stability fixes. Migrate before the sunset date to avoid disruption.

Considerations

• The intelligent boarding API uses OAuth2. Send a Bearer token on every request. See OAuth2 authentication.
• Intelligent boarding records use string references, such as businessReference, personReference, paypointReference, and requestsReference, instead of legacy numeric IDs like appId.

Switch to intelligent boarding

Switching to intelligent boarding doesn’t change what you’ve already boarded with legacy boarding:

• Existing merchants stay boarded. Merchants you boarded with legacy boarding keep processing, and you don’t board them again.
• Applications in progress finish in legacy boarding. Switching doesn’t affect them.
• Stop using legacy boarding when you switch. Boarding through both at the same time can leave your boarding data inconsistent.
• Adding services to a legacy merchant needs Payabli. To request more services through intelligent boarding for a merchant boarded only with legacy boarding, contact Payabli first to convert the merchant’s records.

How the model changes

Legacy boarding merged an application and its paypoint into a single entity. Intelligent boarding separates the business, its people, its paypoints, its payment methods, and its applications. You create the business and its paypoint first, add the people and bank accounts to the business, and then open an application that lists the services the paypoint needs. A person can be linked to more than one business, and a business can back more than one paypoint. For the full model, see Intelligent boarding overview.

Map legacy calls to new endpoints

A single legacy POST /Boarding/app call becomes several intelligent boarding calls, one for each record. The order matters, because each record needs the reference of the one before it:

For a walkthrough of the intelligent boarding sequence with request and response examples, see Board a new business with the API.

Send merchants a boarding link

The legacy boarding link endpoints (/Boarding/applink, /Boarding/linkbyId, /Boarding/linkbyTemplate, and /Boarding/link) have no match in intelligent boarding. Instead, each application has its own link to the hosted boarding application, where the merchant completes it. Create the application with the API, then build the link from the application’s requestsReference:

 https://app.payabli.com/boarding/app/{requestsReference}

How your data changes

Most legacy fields have a match in intelligent boarding, but many move to a different record, change shape, or change format. These patterns cover most of the work. The field-by-field mapping follows in Field mapping.

Data moves to the record it describes

Legacy boarding kept everything on the application. In intelligent boarding, each value belongs to the record it describes:

• The DBA name is doingBusinessAs on the paypoint. The business has no DBA field, so each paypoint carries its own.
• Owners, the signer, and contacts are all people. You set a person’s role in the business on their business link, in businessRelationship: personType, ownershipPercentage, title, isSigner, and isPrimaryController. To choose the signer, set isSigner to true on an owner’s business link. Only an owner can sign. You still send a signer object when you submit, but it holds the signature details, not the signer’s identity.
• Processing volumes move into the business’s processingMetrics object, such as inboundPresentPercent, monthlyReceivablesVolume, and averageReceivableSize. Payout volumes move into payoutMetrics.
• Several paypoints can share one business. A paypoint links to its business with businessReference, so a business with more than one paypoint has a single business record. Paypoints that share a business are called locations.

Flat fields become arrays

Legacy boarding used numbered or prefixed flat fields for addresses and contact details. Intelligent boarding uses arrays:

• Business addresses go in addressDetails, one object for each address, with a type such as legal or mailing.
• Personal addresses go in the person’s addresses array. Use the residential type for a home address.
• Business phone numbers go in the phone array.
• Bank accounts are separate payment methods. Legacy boarding set each account’s role with the numeric bankAccountFunction. In intelligent boarding, each account lists what it’s used for in its usage array, such as deposits, billing, or payOutFunding.

Values change format

Intelligent boarding is stricter about formats than legacy boarding:

• Dates use ISO 8601 format, such as 2015-06-01. Intelligent boarding rejects US-style dates like 06/01/2015 with a 400 error.
• Legal structure takes a fixed set of values in legalStructure, such as llc, corporation, or sole-proprietorship. The legacy btype field accepted free text, such as Corporation or Private Corp. See Legal structure values to convert them.
• Names split into parts. The single legacy owner and contact name fields become firstName and lastName, with an optional middleName.

Custom data

The legacy additionalData object becomes customData. It’s a free-form object on the business and on each person.

Validate before you submit

Legacy boarding had no way to check an application before you submitted it. In intelligent boarding, send a POST request to /v2/requests/{requestsReference}/validate before you submit. Validate checks the business, its people, and its payment methods against what the requested services need. It lists each missing or invalid field by its path on the record, such as business.taxReference. Fix the record, then validate again. Validation doesn’t change the application.

Validate is stricter than the create endpoints. A record can save without a field that validate still reports as missing. Request services on the application before you validate, because many requirements depend on them. For every requirement validate checks, see What validation checks.

Validate also checks for data that legacy boarding didn’t collect, so converted records fail validate until you add it. Expect these fields to come back missing:

• Business: incorporationState and taxIdCountry.
• Volumes: processingMetrics.numberOfTransactions when the application requests Pay In services, and payoutMetrics.numberOfTransactions when it requests Pay Out services. When advancedDelivery is true, the business also needs percentAdvancedDelivery.
• People: nationality on every person except an Employee. People without US nationality need nationalIdNumber instead of ssn.
• Ownership: at least one person marked isPrimaryController.

Submit enforces some validate rules, but not all. Resolve every missing field before you submit.

Track an application’s status

Intelligent boarding application statuses differ from legacy boarding statuses:

• Names and codes are new. Legacy boarding returned boardingStatus codes, such as 3 for Underwriting and 99 for Activated. Intelligent boarding returns a lowercase name in applicationStatus, such as pendingreview, and a number in applicationStatusCode. The names and numbers don’t match the legacy statuses one to one, so build your status handling on the new applicationStatus names instead of reusing your legacy code mapping. See Boarding application statuses.
• Intelligent boarding records status history. To see every transition and what caused it, send a GET request to /v2/requests/{requestsReference}/history.
• Enablement has its own endpoint. After approval, Payabli sets up each requested service with its processor. The application stays approved or autoapproved until every service is live, then moves to activated. To follow its progress, poll GET /v2/requests/{requestsReference}/enablement, because enablement progress has no webhook of its own. See Check enablement after approval.

Status webhooks

Intelligent boarding applications send the same webhook events as legacy boarding, through the same webhook subscriptions. If you already subscribe to the legacy boarding events, you receive them for intelligent boarding applications with no change on your side. Some legacy events are narrower or no longer sent, and some statuses send no webhook:

Two events behave a little differently:

• FailedBoardingApplication now fires for any application that moves to error. Legacy boarding sent it only for processor boarding failures.
• ActivatedMerchant arrives once for each enabled service, as in legacy boarding.

To follow a status that sends no webhook, such as verifying or pendingdocuments, poll the application or its status history.

Act on an application

In legacy boarding, you acted on an application by updating or deleting it. In intelligent boarding, each action is its own endpoint, and the application tells you which actions it allows:

• Check allowedActions first. Application responses list the actions available in the current status. Check the list before you call a lifecycle endpoint.
• Edit only in draft. You can update an application only before you submit it.
• Answer underwriting. When underwriting requests documents or information, the application waits in pendingdocuments or pendingresponse. Upload requested documents with POST /v2/requests/{requestsReference}/documents, then mark the request as answered with provide-documents or provide-response. See Upload documents.
• Withdraw instead of delete. Intelligent boarding has no endpoint to delete an application. Withdraw it instead, with an optional reason. You can withdraw an application in draft, submitted, pendingdocuments, or pendingresponse, and you can’t reopen it afterward.

See Manage applications with the API for every action.

Field mapping

These tables map the fields you send to the legacy POST /Boarding/app endpoint to their intelligent boarding fields. They don’t list fields that are new in intelligent boarding. See the API reference for each endpoint for every field.

To automate the conversion, download the same mapping as JSON:

Businesses

Send these fields to POST /v2/businesses, or in the business object when you create a paypoint.

Legal structure values

Convert each legacy btype value to a legalStructure value:

Delivery days

Legacy boarding split delivery timing across two range fields, whenDelivered and whenProvided. Read them together, and set advancedDeliveryDays to a number of days in the matching range:

Paypoints

Send these fields to POST /v2/paypoints. Create one paypoint for each legacy paypoint you’re migrating. When several paypoints belong to the same business, create the business once and send its businessReference with each paypoint. For a business that opens a new location later, see Add a location for a business with the API.

People

Send these fields to POST /v2/people, once for each owner, contact, and signer. Fields that start with businessRelationship describe the person’s role in the business.

For each item in the legacy ownership array, create a person with businessRelationship.personType set to Owner:

For each item in the legacy contacts array, create a person with businessRelationship.personType set to Employee:

The legacy signer object becomes an owner with businessRelationship.isSigner set to true. If the signer is already in ownership, set isSigner on that person instead of creating a new one. The signature details move to the signer object on submit, which also needs the signature and its signatureType:

Payment methods

Send one item in the data array for each item in the legacy bankData array to POST /v2/payment-methods. Each item also needs type set to bank_account, plus ownerType set to business and accountOwner set to the businessReference. Set isDefault to true on the account that should be the default. If you later send another account with isDefault set to true, that account becomes the default instead.

The legacy numeric bankAccountFunction becomes a list of usage values. A legacy withdrawal account, which Payabli debits for fees, becomes a billing account:

Applications

Send these fields to POST /v2/requests.

Fields with no match

These legacy fields have no intelligent boarding field. Leave them out of your requests:

• taxfillname, faxnumber, payoutCreditLimit, processingRegion, and creditLimit
• whenCharged
• bankData.bankAccountHolderName and bankData.country
• signer.attestationDate and signer.signDate
• recipientEmail, recipientEmailNotification, and resumable: intelligent boarding doesn’t send boarding application emails.
• services.odp.processor, services.odp.processing_region, and services.odp.issuerNetworkSettingsId: Payabli configures these in your organization’s settings.
• attachments: upload documents separately, after you create the application. See Upload documents.

Related resources

See these related resources to help you get the most out of Payabli.