Integrate payments safely with ak:payment-integration

Use ak:payment-integration to design or implement a payment flow with SePay, PayFS, Polar, Stripe, Creem, Dodo Payments, Lemon Squeezy, Paddle, or PayPal. The Skill covers checkout, subscriptions, usage/credit billing, license keys, VietQR and bank transfer flows, signed webhooks, provider-aware orders, refunds, and durable event handling. It is most useful when the provider and business outcome are already known.

Choose ak:payment-integration for provider work

Use ak:payment-integration when

• You need SePay or PayFS for VND, bank-transfer, or VietQR flows.
• You need Polar, Creem, Dodo Payments, Lemon Squeezy, or Paddle for a merchant-of-record SaaS or digital-product checkout, subscriptions, usage billing, or license keys.
• You need Stripe Checkout, Billing, Payment Element, or Connect guidance.
• You need PayPal wallet and card checkout or subscriptions, where you remain the merchant of record.
• You need a unified order model or idempotent webhook processing across providers.

Choose another workflow when

• Provider selection, tax responsibility, merchant-of-record policy, refund policy, or liability is unsettled. Resolve the product and legal decision before implementation.
• The task is only database design. Use ak:databases with the payment contract.
• You need a general backend implementation spanning more than payments. Use ak:cook and name this Skill as specialist guidance.
• You need financial, legal, PCI, or accounting assurance. Use qualified human review; this Skill does not provide it.

Prepare the payment contract and sandbox

Before you start:

• Complete Onboarding, and confirm Engineer Kit is installed for the current runtime and scope.
• Identify the installed provider SDK and API version, framework, database, order schema, authentication, queue, deployment host, and test tools.
• Define currencies, smallest-unit storage, products/prices, taxes, discounts, trials, fulfillment, cancellation, refund, dispute, and reconciliation rules.
• Use sandbox accounts, test products, test payment methods, isolated webhook endpoints, and synthetic customer data. PayFS has no sandbox; treat every PayFS call as live and gate it accordingly.
• Keep provider secret keys and webhook signing secrets (for example SEPAY_SECRET_KEY, PAYFS_WEBHOOK_SECRET, POLAR_ACCESS_TOKEN and POLAR_WEBHOOK_SECRET, Stripe secret and signing keys, CREEM_API_KEY and CREEM_WEBHOOK_SECRET, DODO_PAYMENTS_API_KEY and DODO_PAYMENTS_WEBHOOK_KEY, LEMONSQUEEZY_API_KEY and LEMONSQUEEZY_WEBHOOK_SECRET, PADDLE_WEBHOOK_SECRET, and PAYPAL_CLIENT_ID/PAYPAL_CLIENT_SECRET with the separate PAYPAL_WEBHOOK_ID) and customer data out of prompts, logs, client bundles, command history, and Git.
• State whether package installation, provider API calls, dashboard changes, public tunnels, database writes, emails, refunds, or deployment are allowed.

Provider fees, limits, supported methods, API versions, and compliance requirements change. Confirm them in current provider documentation before making a financial or production decision.

See Runtime adapters for component-level differences.

Choose a provider

Run the Skill

The declared argument shape is [provider] [task]. Name one provider or a deliberate multi-provider boundary, then state the money, order, webhook, test, and publication contract.

/ak:payment-integration "stripe Add a sandbox subscription checkout to the existing SaaS app. Reuse its order schema and auth, pin the installed API version, verify webhook signatures on the raw body, deduplicate events, test renewal and failure paths, and do not create live products, charge cards, refund, or deploy."

/ak:payment-integration "stripe Add a sandbox subscription checkout to the existing SaaS app. Reuse its order schema and auth, pin the installed API version, verify webhook signatures on the raw body, deduplicate events, test renewal and failure paths, and do not create live products, charge cards, refund, or deploy."

$ak:payment-integration "stripe Add a sandbox subscription checkout to the existing SaaS app. Reuse its order schema and auth, pin the installed API version, verify webhook signatures on the raw body, deduplicate events, test renewal and failure paths, and do not create live products, charge cards, refund, or deploy."

Observe the payment stages

1. The run verifies the provider boundary. It confirms the current SDK/API version, environment, checkout product, currency, legal ownership, and project integration points.
2. The run maps the order state machine. Internal and provider identifiers, amounts, currencies, subscriptions, refunds, entitlements, license keys, and terminal states remain explicit.
3. The run creates checkout server-side. Secret-key operations stay behind authenticated server endpoints; only safe client values are returned.
4. The run handles webhooks before fulfillment. It validates the authentic raw request with the provider's own signature scheme (HMAC for SePay, PayFS, Polar, Creem, Lemon Squeezy, and Paddle; Standard Webhooks for Dodo Payments; CRC32 plus RSA certificate verification for PayPal), rejects invalid deliveries, records a unique event, and makes processing idempotent before changing access or money state.
5. The run verifies retries and reconciliation. Duplicate, delayed, out-of-order, failed, refunded, renewed, canceled, and unknown events are exercised against the sandbox contract, or against the live PayFS boundary when that is the provider.
6. The run reports the go-live gap. Changed files, credentials required, provider objects, tests, monitoring, manual dashboard steps, and unapproved financial or deployment actions are listed.

Keep money and external services under approval

• Use server-side secrets and provider-recommended constant-time or SDK signature verification. Do not trust a redirect or client success page as payment confirmation.
• Make fulfillment and entitlement changes idempotent. Persist provider event IDs and preserve enough evidence for replay and reconciliation. PayPal's webhook ID is not delivered in the payload; store it separately from the webhook secrets above and provide it to the verifier.
• Public tunnel tools expose a local endpoint to the internet. Confirm the endpoint, authentication, payload logging, and shutdown plan first.
• The bundled checkout helper generates configuration; it does not complete a provider checkout. Its Polar output embeds the access token in a displayed cURL command, so do not use a live token in interactive output or shell history.
• The bundled per-provider webhook verifiers (SePay, PayFS, Polar, Creem, Dodo Payments, Lemon Squeezy, Paddle, PayPal) create or check signatures for a local test payload; they do not prove a real incoming delivery. The SePay helper's OAuth mode only checks that a Bearer token is present, not that it is valid, and PayFS additionally requires matching the X-Client-API-Key header. Use the provider SDK or a production-grade verifier for the real endpoint.
• Commit, product publication, live webhook registration, refund execution, rollout, and deployment require separate approval.

Verify the result

A complete result should provide:

• The checkout and order-state contract, including amount units, currency, provider IDs, customer mapping, license keys where the provider issues them, and fulfillment boundary.
• Exact changed files, packages, environment-variable names, schema or migration artifacts, queues, and provider objects without secret values.
• Test evidence for checkout creation, invalid input, signature failure, duplicate delivery, retry, out-of-order event, renewal, cancellation, refund, and unknown-event handling as applicable.
• Logs or persisted event evidence that support audit, replay, and reconciliation without storing sensitive payment data unnecessarily.
• A go-live checklist covering provider configuration, secret rotation, endpoint TLS, monitoring, alerting, backup, rollback, support, and approval.

Troubleshoot or continue

Continue with ak:databases for the order ledger, ak:test for independent verification, or the Engineer Kit overview for coordinated delivery.

Know the current limits

• The references are provider snapshots, not live contracts. Current APIs, SDKs, prices, fees, limits, payment methods, tax handling, and store policies require provider verification.
• The Skill does not provide PCI scope determination, legal/tax/accounting advice, fraud underwriting, bank reconciliation guarantees, or production credentials.
• Bundled helper tests cover local JavaScript utilities, not provider network behavior, real webhook delivery, database transactions, financial accuracy, disputes, or production failover.
• Lemon Squeezy is Stripe-owned and in maintenance mode; its JS SDK reference is stale, and a new build should compare it against Stripe Managed Payments before committing to it.
• Multi-provider examples are patterns; currency conversion, refund, discount, commission, and entitlement rules must match the current business ledger.