payabli/integration-skills

payabli-fundamentals

Foundation reference for any Payabli integration work.

Ver código-fonte

Como usar

  1. Copie o comando e verifique o pacote antes de instalar no seu ambiente de agente.
  2. Consulte no original as ferramentas, credenciais e ambientes necessários.
  3. Descreva os dados de entrada e a entrega esperada; confira a saída com as fontes.
npx skills add https://github.com/payabli/integration-skills --skill payabli-fundamentals

Antes de começar

  • A instalação não inclui assinatura de modelo, franquia API ou acesso aos seus arquivos.
  • Estrelas e instalações indicam atividade, não um teste independente de qualidade ou segurança.
Documento original do Skill

Renderizado do repositório de origem, preservando títulos, exemplos, código, tabelas, links e imagens.

Payabli fundamentals

Cross-cutting knowledge every Payabli integration needs. Other Payabli skills load this skill first.

On load

If payabli-integration.md exists at the repo root, read it now. It records the integration's decisions (SDK, products in scope, paypoint model). Apply those decisions to the work below.

Get exact facts from the docs, not from memory

This skill carries procedure. For exact field names, request/response shapes, and error codes, fetch the relevant https://docs.payabli.com/{path}.md page — append .md to any docs URL for lightweight markdown. Do not guess or recall them. Don't hand-construct the doc path either — API-reference endpoint URLs in particular aren't guessable (the slugs don't follow a predictable pattern from the operation name). Take real URLs from the llms.txt index (below) or the Docs MCP. A guessed or wrong path may return a 404, or HTTP 200 with a "Page Not Found" body — so a 200 alone doesn't mean the page exists; check the content.

Some .md pages that resolve API-definition content — API-reference endpoint pages and guide pages with request/response snippets — can render slowly on a cold hit (10–45s). Don't wait one out: if a .md fetch is slow, switch to the HTML URL (same path, drop the .md), which renders quickly, or the Payabli Docs MCP (ask-question-about-payabli). Both return the same content without the cold-render delay.

For broader context, use the section indexes: https://docs.payabli.com/developers/api-reference/llms.txt (API reference) and https://docs.payabli.com/guides/llms.txt (guides). The full catalog of AI-access methods — section indexes, token-saving query params, the OpenAPI spec, and the MCP server — is at https://docs.payabli.com/ai-agents.md.

Before calling an endpoint you haven't already seen documented, confirm it exists rather than guessing a route by analogy with other endpoints. Check the llms.txt index first — it lists the real routes — and use the Docs MCP (ask-question-about-payabli) if you need more. Not every resource has its own endpoint: some are attributes of another record (for example, there is no /Query/StoredMethods — a customer's or vendor's saved methods come back on the GET /Customer/{id} / GET /Vendor/{id} record as StoredMethods[]).

Environments

Select the environment by base URL:

  • Sandbox: https://api-sandbox.payabli.com/api — development and testing, no real money.
  • Production: https://api.payabli.com/api — live; requires Payabli certification before access.

Default to sandbox until the integration is certified. Record the choice in payabli-integration.md under ## Environment.

Authentication

Payabli supports two authentication methods. New integrations should use OAuth2. Never hardcode or commit credentials for either — read them from environment variables or a secrets store.

  • OAuth2 (Bearer) — recommended. Exchange a Client ID/Secret at POST /api/v2/Token/serverside for a short-lived Bearer access token, then send it as Authorization: Bearer <token>. The token's lifetime comes back in expires_in; when it expires the API returns 401 — re-request a new token with the same credentials and retry. The credentials have a configurable lifetime and support secret rotation, giving short-lived, permission-scoped access. Some endpoints accept only OAuth2.
  • API token (`requestToken`). A long-lived API token sent in the `requestToken` header. Suits existing integrations. It coexists with OAuth2, so an existing integration need not migrate.
  • Private vs. public tokens. A private token is for server-side API calls — keep it secret; never put it in client-side code, a bundled env var, or a committed file. A public token is publicly readable and is what every embedded component uses to mount in the browser — all of them require the public token, never a private one (see payabli-accept-payments). Don't send a private token to the browser. This public/private split is separate from the OAuth2-vs-requestToken choice above: OAuth2 and requestToken are both server-side.
  • OAuth2 flow and credential management: https://docs.payabli.com/developers/oauth-authentication.md
  • Authentication overview (choosing a method): https://docs.payabli.com/developers/authentication.md
  • API tokens — types, scopes, and management: https://docs.payabli.com/developers/api-tokens.md

ID hierarchy

Organization is the top-level entity; a paypoint is a merchant. Organizations can group paypoints under optional suborganizations, but suborganizations are not required — many integrations are simply organization → paypoint. The entrypoint (entry name) is Payabli's alias for an organization or paypoint (for example 8cfec329267); it identifies the target in nearly every API call.

  • Entities overview: https://docs.payabli.com/guides/platform-entities-overview.md
  • Entrypoint vs. entry: https://docs.payabli.com/developers/api-reference/api-overview.md

For an ISV managing many merchants: store each merchant's entrypoint in your own system, and pass it as the entry parameter to scope a request to that paypoint. Record the model in payabli-integration.md as single or multi.

Paypoint scoping

A token's scope cannot exceed its parent's. Target a paypoint with its entry (entrypoint). Cross-paypoint operations such as split funding and token sharing require the paypoints to share a parent organization. Detail: https://docs.payabli.com/developers/api-reference/api-overview.md

Products are enabled per paypoint by Payabli. A Missing Gateway Data ... group <moneyin|moneyout> error is always a configuration issue — the product (Pay In or Pay Out) isn't enabled on the paypoint — and only Payabli can fix it. Contact the Payabli team to enable it.

Customer identifiers

Every customer-touching call (create, charge, invoice) must include at least one of the paypoint's configured identifier fields (email, customerNumber, or a custom field); a missing or wrong one returns an opaque Invalid customer identifiers error. You can read what a paypoint requires from the API rather than asking the partner — see references/customer-identifiers.md.

Idempotency

For POST requests that move money, send an idempotencyKey header set to a UUID.

  • Payabli retains the key for about 2 minutes. A repeat within that window returns 409 Conflict.
  • The key is not echoed in webhooks. Correlate via the transId field.
  • On a lost response (timeout), do not assume failure and retry blindly. Confirm via the transaction's webhook (for example ApprovedTransaction) or by querying the transaction first.

Detail: https://docs.payabli.com/developers/api-reference/api-overview.md

Common shapes

A few conventions vary across endpoints and aren't uniform: response envelopes (v2 Pay In code/data, many v1 endpoints isSuccess/responseData, and reads or lists that vary), field casing and names (for example customerId vs PayorId on a transaction), date formats, and the Query API (filters and pagination vary per endpoint; an unrecognized or mis-cased filter field may be ignored or return zero records, and field names are case-sensitive — so verify a filtered count rather than trusting it; see payabli-reporting). When in doubt, check the endpoint's API reference. Detail: https://docs.payabli.com/guides/platform-api-conventions-reference.md

Use current endpoints

Don't call deprecated endpoints. The API reference flags deprecated operations and names the current replacement — follow it. Most common: use v2 Money In (POST /v2/MoneyIn/getpaid), not v1. A deprecated endpoint often still responds in sandbox, so a working call is not proof it's current — confirm against the reference.

PCI scope

How card data is collected drives PCI scope. Embedded components and the temporary token flow keep card data off the partner's servers and minimize scope; handling raw card data directly increases it.

Payabli's PCI material is best-practice engineering guidance, not legal or compliance advice. Do not advise the partner on PCI compliance, scope determination, or audit and attestation requirements. Direct specific PCI questions to the Payabli team. Reference: https://docs.payabli.com/guides/platform-pci-best-practices-overview.md

SDKs and direct API

The Payabli API can be called directly over HTTP, or through an official server SDK (8 languages; they handle auth, typing, and serialization). Both are fully supported — don't assume an SDK. If the project is already in a supported language and nothing requires raw HTTP, suggest the SDK as an option, but don't push it. Detect the project's language to inform that call; see references/sdk-and-language-detection.md. Record what the integration uses in payabli-integration.md under ## SDK (raw-http for direct API). If the SDK lacks an operation or mistypes a request, contact the Payabli team (see API conventions, above).

Ongoing Q&A

For questions during the build, recommend the official Payabli Docs MCP server (it answers questions against the docs and SDK references). To install it, use the payabli-mcp-setup skill.

Report a skill issue

If a skill's guidance is contradicted by the live docs or API — a wrong recommendation, a missing scenario, or a factual error — tell the developer and offer to open a GitHub issue at https://github.com/payabli/integration-skills/issues using the Skill feedback template. Include which skill, which agent, what the skill recommended vs. the correct behavior, and a minimal repro. Never include secrets (API keys, tokens, cardholder data). That tracker is for skill feedback (triaged periodically) — send integration or account problems to the developer's Payabli integration contact, not the issue tracker.

do mesmo repositório

Mais Skills

Todos os Skills
payabli
Comunidade

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.

Instalações / 1h
1
GitHub Stars
0
Atualizado
23 de out.
payabli
Comunidade

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.

Instalações / 1h
1
GitHub Stars
0
Atualizado
23 de out.
payabli
Comunidade

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 and enablement. Moving an existing integration off the legacy /Boarding/ endpoints lives in payabli-boarding-migration. Reads payabli-integration.md on load if present.

Instalações / 1h
1
GitHub Stars
0
Atualizado
23 de out.
payabli
Comunidade

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.

Instalações / 1h
1
GitHub Stars
0
Atualizado
23 de out.