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.