add-payment-flow
Scaffold a payment gateway integration (HyperPay/Moyasar) with checkout, webhook, and transaction tracking. Use when adding payment capabilities.
SKILL.md.claude/skills/add-payment-flow/SKILL.md
GitHubadd-payment-flow
Integrates a Saudi-compatible payment gateway for processing earnest money, commissions, or subscription fees. Supports mada, Visa, Mastercard, and Apple Pay.
Inputs to gather
- Gateway — HyperPay (recommended for Saudi) or Moyasar
- Payment type — one-time (commission, deposit) or recurring (subscription)
- Entity — what is being paid for (dealId, subscriptionId, invoiceId)
- Amount source — fixed or computed from entity (e.g., deal commission amount)
Steps
Create the transactions model via
/add-prisma-model:model transactions { id String @id @default(uuid()) amount Decimal currency String @default("SAR") status String @default("PENDING") // PENDING, COMPLETED, FAILED, REFUNDED gatewayRef String? gatewayData Json? entityType String // "deal", "subscription", "invoice" entityId String userId String organizationId String? createdAt DateTime @default(now()) updatedAt DateTime @updatedAt }Create payment service at
apps/api/libs/payment-gateway.ts:initiateCheckout(amount, currency, entityType, entityId)→ returns checkout URLverifyPayment(gatewayRef)→ returns statusprocessRefund(transactionId)→ initiates refund
Create API routes at
apps/api/routes/payments.ts:POST /api/payments/initiate— create checkout session, return redirect URLPOST /api/payments/webhook— gateway callback (no auth, verify signature)GET /api/payments/transactions— list user/org transactionsPOST /api/payments/:id/refund— admin-only refund
Create checkout page at
apps/web/src/pages/platform/checkout.tsx:- Shows amount, entity details, payment method selection
- Embeds gateway form (HyperPay widget or redirect)
- Success/failure callback pages
Add environment variables:
HYPERPAY_ENTITY_ID=... HYPERPAY_ACCESS_TOKEN=... HYPERPAY_BASE_URL=https://test.oppwa.com # sandbox
Verification checklist
- Sandbox checkout completes successfully
- Webhook updates transaction status to COMPLETED
- Transaction appears in history page
- Refund flow works (admin only)
- Amount matches entity (no manipulation possible)
- Webhook signature verification prevents spoofing
-
/typecheckpasses
Anti-patterns
- Don't trust client-side amount — always compute server-side from entity
- Don't store full card numbers — gateway handles PCI compliance
- Don't skip webhook signature verification
- Don't process payments without creating a transaction record first
- Don't expose sandbox credentials in production