payabli/integration-skills

payabli-boarding

Use when onboarding merchants to Payabli through the API — creating the business, its people, paypoints, and bank accounts, opening a boarding application, validating and submitting it, answering underwriting requests, or tracking an application's status an…

查看源码

使用方法

  1. 复制安装命令,在自己的智能体环境安装前先检查源码包。
  2. 从原始文档核对所需工具、凭据和支持的宿主。
  3. 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/payabli/integration-skills --skill payabli-boarding

开始前需了解

  • 安装不包含模型订阅、API 额度或访问文件的权限。
  • 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
仓库原始内容

按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。

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:

  1. Business — POST /v2/businesses. The create response names the reference businessUuid; it's the value every other call calls businessReference. 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
  2. Paypoint — POST /v2/paypoints, with either businessReference or an inline business object (exactly one). doingBusinessAs lives 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
  3. People — POST /v2/people, once per person, with a businessRelationship object that links them to the business. Fields and allowed values: https://docs.payabli.com/developers/api-reference/people/create-a-person.md
  4. Bank accounts — POST /v2/payment-methods with a data array. Fields and allowed values: https://docs.payabli.com/developers/api-reference/payment-methods/create-payment-methods.md
  5. Application — POST /v2/requests with the businessReference and a services object. 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

  1. Documents — upload any documents the application requires. See "Upload required documents" below.
  2. 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: true on at least one person.
  • isSigner: true on exactly one owner — only an owner can sign. Setting it on one person clears it from the others.
  • ownershipPercentage on every owner, totaling 100 or less, with at least one owner at 25% or more — unless the business's legalStructure is government or non-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/search with the name (plus date of birth or email when you have them). Pass the organization's entry name in entry (OrgEntryName from GET /Organization/read/{orgId}; that response uses capitalized field names) and the org ID in orgId; 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's personReference when its identity details agree. A result with isFromVendor: true has no personReference, 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, or nationalIdNumber after the person exists, so a person created without them can't be fixed with a PATCH. Get them first. https://docs.payabli.com/guides/pay-ops-developer-people-manage.md
  • Check `warnings` on person create. LINK_OWNERSHIP_EXCEEDED comes back with a 201, 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:

  1. List what's needed: GET /v2/requests/{requestsReference}/documents/requirements. Each requirement gives the fieldPath, subjectTypes, allowedFormats, and maxUploads, and a person requirement carries that owner's personReference.
  2. Upload each file: POST /v2/requests/{requestsReference}/documents as multipart form data, with fieldPath, subject, and personReference for a person requirement. Copy these values from the requirement; don't build them yourself.
  3. 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, taxIdCountry from 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, and inboundMotoPercent instead: 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 applicationStatus name, not the number, and check allowedActions before 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 call provide-documents. When it asks a question (pendingresponse), answer it, then call provide-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}/history lists every transition and its cause.
  • After approval, the application stays approved or autoapproved until every service is live, then becomes activated. Enablement sends no webhooks — poll GET /v2/requests/{requestsReference}/enablement, and when blockedOn is merchant_data, fix the fields it lists.

Data formats that trip builds

  • Dates are ISO 8601 (2015-06-01). US-style dates return 400.
  • Send isForeignOwned as true or false explicitly.
  • legalStructure takes fixed values only. Check the business create reference for the list.
  • Names are split: firstName, lastName, optional middleName.

Boundaries

  • Migrating from the legacy /Boarding/* endpoints → payabli-boarding-migration
  • OAuth2 setup, environments, and error handling → payabli-fundamentals
  • Sandbox test data → payabli-testing
来自同一仓库

更多 Skills

全部 Skills
payabli
社区

payabli-accept-payments

Use when writing code that accepts payments through Payabli: charging cards or ACH, integrating embedded payment components or a hosted payment page, handling Apple Pay or Google Pay, or processing voids and refunds. Boundaries — subscriptions: payabli-subscriptions; invoices and payment links: payabli-invoices; disputes and refund-failure recovery: payabli-disputes. Reads payabli-integration.md on load if present.

1小时安装量
1
GitHub Stars
0
最近更新
10月23日
payabli
社区

payabli-bills

Use when building accounts-payable automation on Payabli — capturing vendor bills (manual entry or OCR) and paying them through Pay Out. Distinct from raw payouts (payabli-send-payments): a bill is a captured vendor invoice that you then pay. Reads payabli-integration.md on load if present.

1小时安装量
1
GitHub Stars
0
最近更新
10月23日
payabli
社区

payabli-boarding-migration

Use when moving an existing integration off Payabli's legacy boarding endpoints (/Boarding/app, /Boarding/read, boarding links) to intelligent boarding — converting legacy application payloads to the new records, mapping fields, values, and statuses, or planning the cutover before the legacy sunset. Building boarding from scratch lives in payabli-boarding. Reads payabli-integration.md on load if present.

1小时安装量
1
GitHub Stars
0
最近更新
10月23日
payabli
社区

payabli-certification-prep

Use when a partner wants to rehearse the Payabli certification test scenarios in sandbox before their certification call — running the checks they can self-serve and confirming expected results. This is prep for the call, not self-certification (certification happens with a Payabli SE). Reads payabli-integration.md on load if present.

1小时安装量
1
GitHub Stars
0
最近更新
10月23日