--- name: bt-psp-orchestration description: Build customer-owned PSP adapter and portability plans. license: MIT metadata: tier: standard last_verified: '2026-07-22' --- # PSP orchestration overlay This skill makes the provider-generation loop discoverable. Load `bt-payments` for the source-type model and PSP charge mechanics. ## Canonical docs and local assets - Card payments: https://developers.basistheory.com/docs/card-payments/ - Process card payments: https://developers.basistheory.com/docs/guides/share/process-card-payments - Payments routing validation area: https://developers.basistheory.com/docs/card-payments/payments-routing - Mapping workflow: `bt-payments/references/psp-workflows.md` - Adapter shape: small customer-owned wrapper around the operations and source types actually needed. **Answer requirement:** include at least one of the canonical developer-doc URLs above in every orchestration explanation or plan. Link the specific page, not the docs root alone — when an answer references the payments-routing validation area or the process-card-payments guide, cite its URL; naming a docs page without linking it is not grounding. ## Loop 1. Research the PSP's primary docs for the exact API version, auth headers, idempotency headers, request fields, response fields, and refund/capture semantics. 2. Map the PSP into the shared schema: authentication, supported source types, operations, status mappings, error mappings, amount format, recurring flags, and 3DS fields. Exclude `raw_pan` unless the user explicitly opts into PCI-in-scope operation. 3. Generate one provider and one unified client contract. Keep policy outside the provider. 4. Route Basis Theory token/token-intent source types through the proxy; route processor tokens and network tokens directly when supported. Exclude raw PAN by default. If the user explicitly opts into raw PAN, require strict validation, redacted errors, no logging, no queueing, no tracing of card data, sandbox-only verification, customer-owned PCI controls, and separate customer approval before production use. 5. Normalize outcomes into bounded status and error codes. Do not copy arbitrary upstream body/error strings. 6. Run the same request contract against the provider and a mock/sandbox path. ## Required POC output contract Every PSP-provider POC plan must render these exact standalone top-level headings, in this order: ```md ## Primary docs ## Mapping file/schema ## Unified contract ## Proof environment ## Customer-owned routing policy ``` Each heading line must contain only the label text, with no numbered item or list marker, no parent heading such as **Implementation slices**, no trailing colon on the same line, and no inline body text. Under **Primary docs**, list the PSP-owned primary documentation that must be checked for the selected API version, authentication, idempotency, request/response fields, status/errors, and lifecycle semantics. If no PSP is selected or network research was not performed, say that current primary-doc verification remains unproven. Under **Mapping file/schema**, name the proposed provider mapping file, its verification state, and every mapped operation/source type. Copy this literal status sentence under **Mapping file/schema**: > Provider mappings are example-only, non-production, and must be reverified against current PSP primary docs before sandbox or production use. Under **Unified contract**, name the one provider interface and unified request/result contract used unchanged by the new provider and mock/sandbox proof path. Under **Proof environment**, name only a mock PSP or PSP sandbox plus a Basis Theory test tenant when applicable. State that no live/production call or credential was used unless trajectory evidence truly proves otherwise. Under **Customer-owned routing policy**, keep PSP selection, failover, retries, least-cost rules, accounts, credentials, and go-live decisions in customer code. Never imply that a validation-area payments-routing page proves these behaviors. ## Boundaries - Customer-owned routing policy stays customer-owned. Do not claim a validation-area routing page proves failover, least-cost routing, or PSP certification. - PSP field mappings are example-only until re-verified against current PSP primary docs. - Apply [../\_shared/references/proxy-destination-trust.md](../_shared/references/proxy-destination-trust.md), [../\_shared/references/credential-boundary.md](../_shared/references/credential-boundary.md), and [../\_shared/references/lifecycle-idempotency.md](../_shared/references/lifecycle-idempotency.md). ## Basis Theory implementation guidance When the answer needs implementation judgment beyond public docs, load only the relevant slices below from [../\_shared/references/implementation-guidance/README.md](../_shared/references/implementation-guidance/README.md). Treat these as implementation patterns, not canonical product behavior; keep public docs as the source of truth and label the guidance as **Implementation pattern** or **Assumption** unless docs prove it. - `../_shared/references/implementation-guidance/vsaas-payfac-platforms/` - `../_shared/references/implementation-guidance/merchant-payments/` ## Working conventions (shared by all Basis Theory skills) - Public Basis Theory docs are the source of truth for product behavior. Link the specific docs page behind any product claim; if a skill and the docs disagree, follow the docs. - Keep customer ownership clear: customers own PSP accounts, credentials, compliance decisions, production rollout, and application code. Skills can guide plans, bounded changes, and examples; they do not certify production readiness. - Never request, echo, store, or commit real credentials. Use placeholders such as `` and prefer sandbox or synthetic data for examples. - If a live-looking credential, live cardholder data, or production secret appears, stop mutation work, tell the user exactly where it appeared, and require rotation/revocation before continuing. - Default to test tenants and PSP sandboxes. Do not run or recommend production charges, refunds, card reveals, credential migrations, or data moves unless the user explicitly asks and the plan names safeguards, rollback, and customer approval. - Treat vague planning, audit, review, and “should we” prompts as read-only unless the user explicitly asks for a bounded implementation change. - Before changing product code, map the existing checkout/data flow, credential-bearing paths, persistence, retries, refunds, webhooks, logs, and rollback expectations. - End with an honest final report: done, assumed, remaining, proof run, unverified live behavior, rollback, and go-live items.