/yolfi-payments

name: yolfi-payments
description: Add Yolfi crypto checkout, payment links, and webhook handling to an app through @yolfi/agent or the Yolfi MCP server.

Yolfi Payments Skill

Use this when the user asks to add crypto payments, payment links, checkout, subscriptions, donations, or webhook-based entitlements with Yolfi.

Workflow

1. Inspect the target app first. 2. Identify the framework, env system, server routes, existing checkout code, existing webhook handlers, and entitlement logic. 3. Check auth with `yolfi auth:status` or `yolfi_auth_status`; an explicit `YOLFI_API_KEY` takes precedence over the protected local credential. 4. If auth is missing and the user already has a Yolfi account, use `yolfi setup --agent <slug>` followed by browser authorization and `yolfi checkin --agent <slug>`. The bundled plugin and local MCP server expose `yolfi_agent_setup_start` and `yolfi_agent_checkin`; manually configured remote MCP uses OAuth managed by the host instead. For a new user on the bundled/local transport, first ask them to confirm their email and project name, then call `yolfi_agent_register`. Ask them to open the emailed confirmation link, then call the same tool again with the same arguments. Existing emails must not be re-registered. The tool stores the credential locally, redacts it from model output, and reuses its pending idempotency key across confirmation check-ins. 5. Ask the user for settlement wallet addresses. Never invent them. 6. Ask the user for product name, price, currency, payment type, and recurring interval. 7. Configure settlement settings through `PUT /api/private/organization/current`, then create each webhook through `POST /api/private/organization/webhook-endpoints`. The CLI/local MCP stores the one-time signing secret in the protected local Yolfi config and redacts it from output. 8. List existing paylinks before creating a new one. 9. Create or reuse a paylink. 10. Store paylink ids in env/config, not hard-coded source when avoidable. 11. Add checkout UI or a server route that calls `POST /api/public/payments`. Pass a stable merchant-side customer/user id as `clientReferenceId` whenever webhook-driven attribution or subscription lifecycle updates must resolve that customer. 12. Add webhook signature verification for `X-Yolfi-Signature`. In native (`NONE`) payloads read `data.customer.clientReferenceId`; Stripe-compatible Checkout Session uses `data.object.client_reference_id`, while Stripe-compatible Invoice and Subscription objects use `data.object.metadata.client_reference_id`; Lemon Squeezy-compatible payloads use `meta.custom_data.client_reference_id`. 13. Connect webhook events to the app's existing entitlement/business logic when possible. 14. Verify payment status with `GET /api/public/payments/:id`. 15. Report changed files and exact verification commands.

Webhook Contract

• Publicly supported endpoint adapters are `NONE`, `STRIPE`, and `LEMON_SQUEEZY`. Treat `NONE` as native Yolfi payload format, not as the absence of a provider.
• Create independent endpoints through `POST /api/private/organization/webhook-endpoints`; the removed organization-level `webhookUrl` and `webhookAdapter` fields are not supported.
• Each endpoint has its own signing secret. CLI/MCP create and rotate store it in the protected local config; use the endpoint id for local verification or provision `YOLFI_WEBHOOK_SECRET` through the target deployment's secret manager.
• `YOLFI_API_KEY` authorizes Yolfi API calls and must never be used to verify webhook signatures. Verify `X-Yolfi-Signature` with that endpoint's signing secret only.
• Endpoint create/update accepts optional flat `metadataFilters` string maps (at most 10 entries; keys at most 100 characters; values at most 255 characters); a delivery must match every configured key/value.
• Browser setup and agent-first signup each issue a scoped `yolfi_agent_*` credential. Neither credential is a webhook signing secret.
• Analytics routing uses `website_id`. Provision an adapter `NONE` endpoint with `metadataFilters: { "website_id": "<websiteId>" }`.

Do Not

• Do not invent wallet addresses.
• Do not invent prices, plans, currencies, or recurring intervals.
• Do not commit API keys or webhook secrets.
• Do not print or echo the `yolfi_agent_*` credential returned during check-in.
• Do not pass webhook signing secrets as MCP arguments or CLI flags.
• Do not replace existing billing logic unnecessarily.
• Do not use frontend redirect as proof of payment.
• Do not disable paylinks without explicit user approval.
• Do not duplicate webhook business handlers when an existing handler can be reused.
• Do not use email as the primary subscription identity when `clientReferenceId` can be supplied.