Come usare
- Copia il comando e controlla il pacchetto prima di installarlo nel tuo ambiente agente.
- Controlla strumenti, credenziali e ambienti richiesti nel documento originale.
- Descrivi input e risultato desiderato; confronta l’output con le fonti.
npx skills add https://github.com/payabli/integration-skills --skill payabli-boardingPrima di iniziare
- L’installazione non include abbonamenti, quote API o accesso ai file.
- Stelle e installazioni indicano attività, non un test indipendente di qualità o sicurezza.
Contenuto dal repository con titoli, esempi, codice, tabelle, link e immagini preservati.
Payabli boarding
Board merchants with intelligent boarding, which uses the /v2 businesses, people, paypoints, payment methods, and applications (/v2/requests) endpoints.
If boarding calls fail unexpectedly
Intelligent boarding is an opt-in beta. If boarding calls return 400 or 500-range errors that the response doesn't explain, such as on the first call, tell the developer to check with their Payabli contact that intelligent boarding is enabled for their account and that their API credentials have the right permissions. A 400 with field errors is a validation problem, not this.
Load fundamentals first
If payabli-fundamentals is not already loaded, load it now, then continue.
On load
If payabli-integration.md exists at the repo root, read it; honor its ## SDK value.
Authenticate with OAuth2 only
The boarding endpoints accept only an OAuth2 Bearer token. Use the OAuth2 flow from payabli-fundamentals. https://docs.payabli.com/developers/oauth-authentication.md
Create separate records in order
Legacy boarding put everything in one application. Intelligent boarding splits it into records that reference each other by UUID. The application only requests services for a business that already exists. Read the model first: https://docs.payabli.com/guides/pay-ops-boarding-object-model-overview.md
Create the records in this order, because each needs a reference from the one before it:
- Business —
POST /v2/businesses. The create response names the referencebusinessUuid; it's the value every other call callsbusinessReference. Or skip this call and create the business inline in step 2. Fields and allowed values: https://docs.payabli.com/developers/api-reference/businesses/create-a-business.md - Paypoint —
POST /v2/paypoints, with eitherbusinessReferenceor an inlinebusinessobject (exactly one).doingBusinessAslives here, not on the business; each location is its own paypoint on the same business. Fields and allowed values: https://docs.payabli.com/developers/api-reference/paypoints/create-a-paypoint.md - People —
POST /v2/people, once per person, with abusinessRelationshipobject that links them to the business. Fields and allowed values: https://docs.payabli.com/developers/api-reference/people/create-a-person.md - Bank accounts —
POST /v2/payment-methodswith adataarray. Fields and allowed values: https://docs.payabli.com/developers/api-reference/payment-methods/create-payment-methods.md - Application —
POST /v2/requestswith thebusinessReferenceand aservicesobject. Fields and allowed values: https://docs.payabli.com/developers/api-reference/applications/create-an-application.md
Send requestTemplate on every application. The API accepts an application without one, but Payabli assigns the underwriting policy from the template, so a submitted application without one errors in review. The partner chooses the template. Before you create the application, ask the developer which template to use, unless they already named one. If you can't ask, stop before creating the application and report that you need a template. Never pick one from the template list yourself. https://docs.payabli.com/guides/pay-ops-developer-templates-manage.md
- Documents — upload any documents the application requires. See "Upload required documents" below.
- Validate, then submit. https://docs.payabli.com/developers/api-reference/applications/validate-an-application.md and https://docs.payabli.com/developers/api-reference/applications/submit-an-application.md
To have the merchant complete the application in Payabli's hosted boarding application instead, create it with the API and send them https://app.payabli.com/boarding/app/{requestsReference} (sandbox: https://app-sandbox.payabli.com/boarding/app/{requestsReference}). If the partner uses a custom domain for the hosted application, use that domain instead of Payabli's.
Follow the end-to-end walkthrough for request bodies: https://docs.payabli.com/guides/pay-ops-developer-boarding-new-entity-paypoint.md. For more services on an existing merchant, see https://docs.payabli.com/guides/pay-ops-developer-boarding-add-services.md; for another location, https://docs.payabli.com/guides/pay-ops-developer-boarding-new-location.md.
Link every person as Owner or Employee
Set the role in businessRelationship.personType, and use only `Owner` and `Employee`. Validation holds every other role (Contact, Director, Signer, AuthorizedUser) to the owner requirements. The API also drops ownershipPercentage on non-owner links without an error, so those people can never pass. Link contacts and other non-owners as Employee.
On the business link, also set:
isPrimaryController: trueon at least one person.isSigner: trueon exactly one owner — only an owner can sign. Setting it on one person clears it from the others.ownershipPercentageon every owner, totaling 100 or less, with at least one owner at 25% or more — unless the business'slegalStructureisgovernmentornon-profit.
https://docs.payabli.com/guides/pay-ops-developer-people-manage.md
Reuse people across businesses
A person is one record that can be linked to many businesses. The link holds the per-business role, title, ownership, and signer flag.
- Search before you create.
POST /v2/people/searchwith the name (plus date of birth or email when you have them). Pass the organization's entry name inentry(OrgEntryNamefromGET /Organization/read/{orgId}; that response uses capitalized field names) and the org ID inorgId; both are required. A paypoint's entry name limits the search to that paypoint's business and misses owners of your other merchants. Reuse a match'spersonReferencewhen its identity details agree. A result withisFromVendor: truehas nopersonReference, so create that person. https://docs.payabli.com/developers/api-reference/search-people.md - Conflicting details mean stop. If a match or two input rows disagree on identity (date of birth, address), ask the developer. Don't create a second record, and don't overwrite the existing one.
- Link, don't recreate. Attach an existing person with the business people endpoint. In a batch, create each unique person once and link them once per business. https://docs.payabli.com/developers/api-reference/businesses/link-a-person-to-a-business.md
- Collect identity before you create. You can't add or change
dateOfBirth,ssn, ornationalIdNumberafter the person exists, so a person created without them can't be fixed with aPATCH. Get them first. https://docs.payabli.com/guides/pay-ops-developer-people-manage.md - Check `warnings` on person create.
LINK_OWNERSHIP_EXCEEDEDcomes back with a201, but the person isn't linked.
Make batch runs safe to rerun
Keep a ledger keyed by your own row ID. Store each reference as it's created (business, paypoint, people, payment methods, application) and the last completed step. On a rerun, skip completed steps and continue from the ledger. Don't rely on create calls to catch repeats: some reject a duplicate (a reused tax reference returns an error), but people don't. Hold a row with gaps instead of submitting it, and finish the rest.
Bank accounts
Send each account as an item in the data array, with type: bank_account, accountOwner (the businessReference), and ownerType: business. nickname is required by validate and is your own label for the account, so set one even when the merchant didn't supply it. Each account's usage array says what it's for: deposits for funding, billing for the account Payabli debits for fees, payOutFunding for payouts. Between them the accounts need deposits and either billing or refunds. Don't use withdrawals.
Mark exactly one account isDefault: true. Sending isDefault: true on a later account moves the default to it. To check which account is the default, read the business (GET /v2/businesses/{businessReference}); a single payment-method read doesn't return isDefault. https://docs.payabli.com/guides/pay-ops-developer-payment-methods-manage.md
Upload required documents
The template and Payabli's business rules decide which documents an application needs. For example, a business with an annualRevenue of $1,000,000 or more needs bank statements. Upload them through the API before you submit:
- List what's needed:
GET /v2/requests/{requestsReference}/documents/requirements. Each requirement gives thefieldPath,subjectTypes,allowedFormats, andmaxUploads, and a person requirement carries that owner'spersonReference. - Upload each file:
POST /v2/requests/{requestsReference}/documentsas multipart form data, withfieldPath,subject, andpersonReferencefor a person requirement. Copy these values from the requirement; don't build them yourself. - To replace a file, delete it with its
documentReference, then upload the new one.
Validate reports a required document as missing until it's uploaded. A 400 VALIDATION_ERROR on upload means the file doesn't fit the requirement; read the message. Get real documents from the developer or the merchant; never generate placeholder files outside sandbox tests. https://docs.payabli.com/guides/pay-ops-developer-applications-manage.md#upload-documents
Validate before every submit
POST /v2/requests/{requestsReference}/validate reports every missing or invalid field by its path on the record (for example business.taxReference). It doesn't change anything. Treat it as the source of truth for readiness:
- Request services first. Requirements depend on the requested services; with no services, validate checks the requirements for every service.
- Fill gaps with real data, never inferred data. When validate reports a missing field, get the value from the developer or the merchant. Don't derive it (formation state from an address, nationality from a country,
taxIdCountryfrom the tax ID's format) or default it (100 for a percentage) just to pass validate. Invent values only for sandbox test data the developer asked for. - Validate is stricter than create. A record can save without fields validate still requires, so a successful create doesn't mean the data is complete.
- `business.processingMetrics.environments` means the sales channel split. Validate can report this path, but no such field exists. Set
inboundPresentPercent,inboundOnlinePercent, andinboundMotoPercentinstead: at least one above 0, summing to 100. - Submit doesn't enforce every validate rule. An application can submit with gaps validate would have caught, and then stall in review. Always validate, fix the records (business, people, bank accounts — not the application), and validate again until the result is valid.
For what validation checks on each record, see the Validate an application section of https://docs.payabli.com/guides/pay-ops-developer-applications-manage.md
Submit
POST /v2/requests/{requestsReference}/submit, while the application is in draft. Send a signer object with the signature details: signature and signatureType, or signedDocumentReference if the signer signed in your own e-sign tool. Set acceptance and pciAttestation to true only when the signer actually accepted the terms and attested; Payabli records false when they're left out. To pick the signer on this call, send their personReference in signer. Payabli takes the signer's identity from their person record and business link, so fix those before you submit. It fails with 422 SIGNER_REQUIRED if no owner is marked isSigner, and 422 SIGNER_NOT_OWNER if the named signer isn't an owner. https://docs.payabli.com/guides/pay-ops-developer-applications-manage.md
After submit
- Branch on the
applicationStatusname, not the number, and checkallowedActionsbefore calling a lifecycle endpoint. https://docs.payabli.com/guides/pay-ops-boarding-application-status-reference.md - Edit the application only in
draft. After submit, fix data on the records, not the application. - When underwriting asks for documents (
pendingdocuments), upload them with the document endpoints first, then callprovide-documents. When it asks a question (pendingresponse), answer it, then callprovide-response. Neither call takes a body, and both return the application to review. - Withdraw an application instead of deleting it, because there's no delete. Withdrawal is final.
GET /v2/requests/{requestsReference}/historylists every transition and its cause.- After approval, the application stays
approvedorautoapproveduntil every service is live, then becomesactivated. Enablement sends no webhooks — pollGET /v2/requests/{requestsReference}/enablement, and whenblockedOnismerchant_data, fix the fields it lists.
Data formats that trip builds
- Dates are ISO 8601 (
2015-06-01). US-style dates return400. - Send
isForeignOwnedastrueorfalseexplicitly. legalStructuretakes fixed values only. Check the business create reference for the list.- Names are split:
firstName,lastName, optionalmiddleName.
Boundaries
- Migrating from the legacy
/Boarding/*endpoints →payabli-boarding-migration - OAuth2 setup, environments, and error handling →
payabli-fundamentals - Sandbox test data →
payabli-testing