payment-gateway

name	payment-gateway
description	Process payments via Stripe, PayPal, or ACH. Use when paying invoices, processing customer payments, or managing payment methods. Handles payment scheduling, execution, and confirmation with full audit trail.

Payment Gateway Skill

Purpose

Processes payments securely through integrated payment gateways (Stripe, PayPal, ACH), with proper authorization, audit logging, and error handling.

Triggers

• Invoice approved and ready for payment
• Customer payment submitted
• Scheduled payment due date reached
• Manual payment initiated

Capabilities

1. Payment Processing - Execute payments via Stripe/PayPal/ACH
2. Payment Scheduling - Schedule future payments
3. Payment Confirmation - Verify payment succeeded
4. Refund Processing - Handle refunds and reversals
5. Payment Method Management - Store and manage payment methods
6. Webhook Handling - Process payment status webhooks

Instructions

Step 1: Validate Payment Request

Required fields:

• tenant_id - For multi-tenant isolation
• invoice_id or amount - What to pay
• payment_method - stripe, paypal, ach
• approved_by - User ID who approved payment
• scheduled_date - When to execute (can be immediate)

Validations:

• Invoice status is 'approved'
• Amount matches invoice amount
• Payment method is configured for tenant
• User has permission to approve payments
• Sufficient funds (if applicable)

Step 2: Execute Payment

Stripe Payment

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

const payment_intent = await stripe.paymentIntents.create({
  amount: invoice.amount,  // cents
  currency: invoice.currency,
  description: `Invoice ${invoice.invoice_number} - ${invoice.vendor_name}`,
  metadata: {
    tenant_id: invoice.tenant_id,
    invoice_id: invoice.id,
  },
});

// Confirm payment
const confirmed = await stripe.paymentIntents.confirm(payment_intent.id, {
  payment_method: tenant_payment_method_id,
});

ACH Payment

// Via Stripe or Plaid
const transfer = await stripe.transfers.create({
  amount: invoice.amount,
  currency: invoice.currency,
  destination: vendor_stripe_account_id,
});

PayPal Payment

// Via PayPal SDK
const payment = await paypal.createPayment({
  amount: cents_to_dollars(invoice.amount),
  currency: invoice.currency,
  recipient: vendor_paypal_email,
});

Step 3: Update Invoice Status

On success:

UPDATE invoices
SET status = 'paid',
    paid_at = NOW(),
    updated_at = NOW()
WHERE id = $1 AND tenant_id = $2;

On failure:

• Log error to agent_runs table
• Create alert for manual review
• Do NOT mark as paid

Step 4: Audit Log

INSERT INTO audit_log (tenant_id, user_id, action, entity_type, entity_id, changes)
VALUES (
  $1,  -- tenant_id
  $2,  -- user_id (approved_by)
  'approve',  -- action
  'invoices',  -- entity_type
  $3,  -- invoice_id
  jsonb_build_object(
    'payment_method', 'stripe',
    'payment_intent_id', payment_intent.id,
    'amount', invoice.amount,
    'status', 'paid'
  )
);

Step 5: Confirmation

Return payment confirmation:

{
  "success": true,
  "invoice_id": "uuid",
  "payment_id": "pi_1234...",  // Stripe payment intent ID
  "amount": 50000,  // cents
  "currency": "USD",
  "status": "paid",
  "paid_at": "2026-01-15T14:30:00Z",
  "payment_method": "stripe",
  "confirmation_number": "..."
}

Payment Scheduling

For future payments:

INSERT INTO scheduled_payments (
  tenant_id, invoice_id, amount, currency,
  payment_method, scheduled_date, status
)
VALUES ($1, $2, $3, $4, $5, $6, 'pending');

Cron job checks scheduled_payments daily and executes when scheduled_date <= NOW().

Webhook Handling

Process Stripe webhooks:

• payment_intent.succeeded - Mark invoice as paid
• payment_intent.payment_failed - Alert user, retry or manual review
• charge.refunded - Create refund transaction

Error Handling

• Insufficient Funds - Alert user, reschedule payment
• Payment Method Invalid - Request updated payment method
• API Error - Retry with exponential backoff (3 attempts)
• Network Timeout - Check payment status before retry (idempotency)
• Declined Payment - Alert user, mark for manual review

Integration Points

• stripe-integrator (Integration worker) - Stripe API
• paypal-integrator (Integration worker) - PayPal API
• payment-processor (AP worker) - Payment execution logic
• audit-trail - Immutable audit log

Models

• Payment Logic: Deterministic (no LLM)
• Error Analysis: Claude Sonnet 4 (for complex error scenarios)

Security

• Idempotency - Use idempotency keys for Stripe to prevent duplicate charges
• PCI Compliance - Never store full credit card numbers
• Secrets Management - API keys in environment variables, never in code
• Rate Limiting - Respect payment gateway rate limits
• Audit Trail - Log all payment attempts (success and failure)
• User Authorization - Verify user can approve payments (RBAC)
• Amount Verification - Confirm amount matches invoice before payment

---

Invoke this skill when executing vendor payments or processing customer payments through integrated gateways.