Tích hợp thanh toán an toàn với ak:payment-integration

Dùng ak:payment-integration để thiết kế hoặc triển khai payment flow với SePay, PayFS, Polar, Stripe, Creem, Dodo Payments, Lemon Squeezy, Paddle hoặc PayPal. Skill bao quát checkout, subscription, usage/credit billing, license key, VietQR và bank transfer, signed webhook, order nhận biết provider, refund cùng xử lý event bền vững. Skill hữu ích nhất khi provider và business outcome đã rõ.

Chọn ak:payment-integration cho công việc provider

Dùng ak:payment-integration khi

• Bạn cần SePay hoặc PayFS cho VND, bank transfer hoặc VietQR.
• Bạn cần Polar, Creem, Dodo Payments, Lemon Squeezy hoặc Paddle cho checkout merchant-of-record của SaaS/digital product, subscription, usage billing hoặc license key.
• Bạn cần guidance Stripe Checkout, Billing, Payment Element hoặc Connect.
• Bạn cần checkout ví/thẻ PayPal hoặc subscription, nơi bạn vẫn là merchant of record.
• Bạn cần order model hợp nhất hoặc webhook processing idempotent giữa nhiều provider.

Chọn workflow khác khi

• Việc chọn provider, trách nhiệm thuế, merchant-of-record policy, refund policy hoặc liability chưa thống nhất. Giải quyết quyết định product và legal trước implementation.
• Task chỉ là database design. Dùng ak:databases với payment contract.
• Bạn cần backend implementation tổng quát rộng hơn thanh toán. Dùng ak:cook và nêu Skill này như specialist guidance.
• Bạn cần đảm bảo tài chính, pháp lý, PCI hoặc kế toán. Hãy dùng human review đủ chuyên môn; Skill này không cung cấp đảm bảo đó.

Chuẩn bị payment contract và sandbox

Trước khi bắt đầu:

• Hoàn thành Làm quen và xác nhận Engineer Kit đã được cài cho runtime cùng scope hiện tại.
• Xác định provider SDK và API version đã cài, framework, database, order schema, authentication, queue, deployment host cùng test tool.
• Xác định currency, cách lưu smallest unit, product/price, tax, discount, trial, fulfillment, cancellation, refund, dispute cùng reconciliation rule.
• Dùng sandbox account, test product, test payment method, webhook endpoint cô lập cùng customer data giả lập. PayFS không có sandbox; coi mọi call PayFS là live và gate tương ứng.
• Giữ provider secret key cùng webhook signing secret (ví dụ SEPAY_SECRET_KEY, PAYFS_WEBHOOK_SECRET, POLAR_ACCESS_TOKEN và POLAR_WEBHOOK_SECRET, Stripe secret/signing key, CREEM_API_KEY và CREEM_WEBHOOK_SECRET, DODO_PAYMENTS_API_KEY và DODO_PAYMENTS_WEBHOOK_KEY, LEMONSQUEEZY_API_KEY và LEMONSQUEEZY_WEBHOOK_SECRET, PADDLE_WEBHOOK_SECRET, cùng PAYPAL_CLIENT_ID/PAYPAL_CLIENT_SECRET với PAYPAL_WEBHOOK_ID riêng) và customer data ngoài prompt, log, client bundle, command history cùng Git.
• Nêu rõ có cho phép cài package, gọi provider API, đổi dashboard, mở public tunnel, ghi database, gửi email, refund hay deploy không.

Fee, limit, payment method được hỗ trợ, API version cùng compliance requirement của provider thay đổi theo thời gian. Xác nhận trong tài liệu provider hiện tại trước quyết định tài chính hoặc production.

Xem Runtime adapter để hiểu khác biệt theo từng component.

Chọn provider

Chạy Skill

Argument shape được khai báo là [provider] [task]. Nêu một provider hoặc ranh giới multi-provider có chủ đích, rồi mô tả contract về tiền, order, webhook, test cùng publication.

/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."

Quan sát các giai đoạn thanh toán

1. Lần chạy xác minh ranh giới provider. Skill xác nhận SDK/API version, environment, checkout product, currency, legal ownership cùng integration point thực tế của project.
2. Lần chạy lập bản đồ order state machine. Internal/provider identifier, amount, currency, subscription, refund, entitlement, license key cùng terminal state luôn rõ ràng.
3. Lần chạy tạo checkout ở server. Thao tác dùng secret key nằm sau server endpoint đã xác thực; client chỉ nhận value an toàn.
4. Lần chạy xử lý webhook trước fulfillment. Skill xác minh raw request thật bằng scheme signature riêng của provider (HMAC cho SePay, PayFS, Polar, Creem, Lemon Squeezy và Paddle; Standard Webhooks cho Dodo Payments; CRC32 kết hợp xác minh chứng chỉ RSA cho PayPal), từ chối delivery không hợp lệ, ghi unique event và bảo đảm processing idempotent trước khi đổi access hay money state.
5. Lần chạy xác minh retry và reconciliation. Event trùng, trễ, sai thứ tự, lỗi, refunded, renewed, canceled cùng unknown được kiểm tra trên sandbox contract, hoặc trên ranh giới live của PayFS khi đó là provider.
6. Lần chạy báo cáo gap go-live. Tệp đổi, credential cần có, provider object, test, monitoring, dashboard step thủ công cùng financial hoặc deployment action chưa duyệt được liệt kê.

Giữ tiền và external service dưới quyền duyệt

• Dùng secret ở server và cơ chế constant-time hoặc SDK signature verification do provider khuyến nghị. Không coi redirect hay client success page là xác nhận thanh toán.
• Giữ fulfillment cùng entitlement change idempotent. Lưu provider event ID và đủ bằng chứng cho replay cùng reconciliation. Webhook ID của PayPal không được gửi kèm payload; lưu nó tách biệt với các webhook secret ở trên và cấp cho verifier.
• Public tunnel tool đưa local endpoint ra internet. Xác nhận endpoint, authentication, payload logging cùng kế hoạch shutdown trước.
• Checkout helper đi kèm tạo configuration; nó không hoàn tất provider checkout. Output Polar nhúng access token vào lệnh cURL được hiển thị, vì vậy đừng dùng live token trong interactive output hoặc shell history.
• Các webhook verifier theo provider đi kèm (SePay, PayFS, Polar, Creem, Dodo Payments, Lemon Squeezy, Paddle, PayPal) tự tạo hoặc kiểm tra signature cho payload test cục bộ; chúng không chứng minh real incoming delivery. OAuth mode của helper SePay chỉ kiểm tra có Bearer token, không kiểm tra token hợp lệ, còn PayFS còn yêu cầu khớp header X-Client-API-Key. Dùng provider SDK hoặc verifier đạt chuẩn production cho endpoint thật.
• Commit, product publication, live webhook registration, refund execution, rollout cùng deployment cần phê duyệt riêng.

Xác minh kết quả

Kết quả hoàn tất nên cung cấp:

• Checkout cùng order-state contract, gồm amount unit, currency, provider ID, customer mapping, license key nếu provider phát hành, cùng fulfillment boundary.
• Chính xác tệp đổi, package, tên environment variable, schema hay migration artifact, queue cùng provider object mà không có secret value.
• Bằng chứng test cho checkout creation, invalid input, signature failure, duplicate delivery, retry, out-of-order event, renewal, cancellation, refund cùng unknown-event handling khi áp dụng.
• Log hoặc persisted event evidence hỗ trợ audit, replay cùng reconciliation mà không lưu payment data nhạy cảm quá mức.
• Go-live checklist bao gồm provider configuration, secret rotation, endpoint TLS, monitoring, alerting, backup, rollback, support cùng phê duyệt.

Xử lý sự cố hoặc tiếp tục

Tiếp tục với ak:databases cho order ledger, ak:test cho verification độc lập hoặc Tổng quan Engineer Kit cho delivery được điều phối.

Biết các giới hạn hiện tại

• Reference là snapshot provider, không phải live contract. API, SDK, price, fee, limit, payment method, tax handling cùng store policy hiện tại cần được xác minh với provider.
• Skill không cung cấp PCI scope determination, tư vấn pháp lý/thuế/kế toán, fraud underwriting, bảo đảm bank reconciliation hay production credential.
• Helper test đi kèm kiểm tra JavaScript utility cục bộ, không kiểm tra provider network behavior, real webhook delivery, database transaction, financial accuracy, dispute hay production failover.
• Lemon Squeezy thuộc sở hữu Stripe và ở chế độ bảo trì; reference JS SDK của nó đã cũ, và build mới nên so sánh với Stripe Managed Payments trước khi chọn.
• Ví dụ multi-provider là pattern; currency conversion, refund, discount, commission cùng entitlement rule phải khớp business ledger hiện tại.