payment-flow-test-author

Overview

The three highest-incident payment surfaces after the happy path - refunds, disputes, and webhook handling - are one suite-authoring job, because they share the same substrate: the gateway's async state machine. This workflow builds all three phases in dependency order, driven by the canonical states in payment-flow-states-reference.

Common bugs each phase catches: double-refund and partial-refund-not-summing (Phase 1); missed evidence deadlines and unreconciled chargeback fees (Phase 2); non-idempotent redelivery handling and spoofable handlers (Phase 3).

When to use

• New payment integration; need refund / dispute / webhook coverage.
• A refund- or webhook-related incident; need to backfill tests.
• Gateway migration; need to re-validate flow logic.

Phase 0 - Map the state machine

Before writing any test, translate the canonical lifecycle (created → requires_action → processing → succeeded → refunded / disputed) into your gateway's vocabulary using payment-flow-states-reference. Every assertion below is on a state from that grid, and every async assertion waits on the webhook, never the synchronous API return.

Phase 1 - The refund matrix

Inventory refund touchpoints

grep -rn 'refund\|Refund\|REFUND' --include='*.{ts,js,py,java,go,rb,cs}' .

Categorise per gateway + per code path (order cancellation, CS portal, subscription downgrade, dispute-lost automation).

The 7 canonical refund cases

For each (gateway, touchpoint):

Per-gateway refund APIs

Stripe, per docs.stripe.com/refunds:

test('over-refund rejected', async () => {
  const intent = await createSucceededIntent({ amount: 1000 });
  await expect(
    stripe.refunds.create({ payment_intent: intent.id, amount: 1500 })
  ).rejects.toThrow(/refund_amount_exceeds_charge_amount/);
});

Adyen refunds are async, per docs.adyen.com/online-payments/refund: the call returns [refund-received]; completion arrives as a [REFUND] notification - assert via webhook, not the sync response. PayPal uses CapturesRefundRequest per developer.paypal.com/docs/api/payments/v2#captures_refund; Braintree requires settlement first (gateway.testing.settle, sandbox-only) before gateway.transaction.refund.

Refund idempotency

test('idempotent refund', async () => {
  const intent = await createSucceededIntent({ amount: 1000 });
  const key = 'refund-' + intent.id;
  const r1 = await stripe.refunds.create({ payment_intent: intent.id, amount: 500 }, { idempotencyKey: key });
  const r2 = await stripe.refunds.create({ payment_intent: intent.id, amount: 500 }, { idempotencyKey: key });
  expect(r1.id).toBe(r2.id);
});

Without idempotency, network retries double-refund the customer.

Phase 2 - The chargeback / dispute suite

1. Pick the 3-5 reason codes most common for your business from references/reason-codes.md - each code has different evidence requirements.
2. Trigger a disputable charge in the gateway's test mode (Stripe pm_card_createDispute per docs.stripe.com/testing#disputes; an Adyen [CHARGEBACK] notification per docs.adyen.com/risk-management/disputes-api; a PayPal sandbox dispute per developer.paypal.com/docs/api/customer-disputes/v1).
3. Assert the dispute lands in needs_response (or the gateway equivalent) with the expected reason.
4. Submit evidence before evidence_details.due_by and assert has_evidence is set, per docs.stripe.com/disputes/responding.
5. Drive each disposition - won (winning evidence), lost (no response), accepted - and confirm the final state via the charge.dispute.closed webhook.
6. Verify the ledger reverses funds plus the chargeback fee on a lost dispute.

test('lost dispute reverses funds in ledger', async () => {
  const intent = await createSucceededIntent({ amount: 1000 });
  const dispute = await triggerLostDispute(intent);
  await waitForChargebackEvent();

  const ledger = await getLedgerEntries(intent.id);
  expect(ledger).toContainEqual(expect.objectContaining({ type: 'chargeback', amount: -1000 }));
  expect(ledger).toContainEqual(expect.objectContaining({ type: 'chargeback_fee' }));
});

Phase 3 - Webhook replay via gateway-native simulators

Payment webhooks are the source of truth for async transitions, so every handler must be signature-verified, idempotent, order-tolerant, and replay-safe.

1. Confirm the handler reads the raw request body - signature verification fails on parsed-then-restringified bytes.
2. Run the four-case signature gauntlet (unsigned / wrong-secret / valid / expired-timestamp) for your gateway; the per-gateway signature schemes, simulator commands, and the full gauntlet code are in references/replay-simulators.md.
3. Add the idempotency dedup test - redelivery must not double-process:

test('redelivered webhook handled idempotently', async () => {
  const payload = makeWebhookPayload({ type: 'payment_intent.succeeded' });
  const sig = signPayload(payload);

  await postWebhook(payload, sig);
  await postWebhook(payload, sig);  // redelivery

  const rows = await db.payment_records.count({ event_id: payload.id });
  expect(rows).toBe(1);             // processed exactly once
});

4. Wire the gateway's replay simulator and drive a real event end to end:

stripe trigger payment_intent.succeeded    # synthetic event to the forward URL
stripe events resend evt_test_12345        # replay a captured event (30-day window)

5. Add the harder recovery scenarios - out-of-order delivery, mid-handler crash, archive replay, per-gateway suite layout - from references/advanced-recovery-scenarios.md.

For generic webhook receiver testing (Standard-Webhooks signature scheme, non-payment senders, inbound replay hardening), use webhook-delivery-tester in the qa-notifications plugin; this phase covers the payment-gateway-specific surface only.

Emit the coverage matrix

# tests/payment/flow-matrix.yaml
matrix:
  gateways: [stripe, adyen, paypal, braintree]
  refund_variants: [full, partial, multiple-partials, over-refund, already-refunded, failed-charge, disputed-charge]
  dispute_cells: ["Visa 10.4", "Visa 13.1", "Mastercard 4855"] # x [won, lost, accepted]
  webhook_cases: [signature-gauntlet, idempotent-redelivery, out-of-order, crash-recovery]

Report the matrix per release and document deliberate gaps.

Anti-patterns

Limitations

• Real chargebacks take weeks. Test mode collapses the timeline; production verification needs production traffic.
• Reason codes change. Visa / Mastercard publish updates; test data goes stale annually.
• Bank-declined refunds simulate poorly; rely on platform-documented test cases.
• Bank-initiated webhooks aren't always test-mode-triggerable.

References

• Stripe refunds: docs.stripe.com/refunds; disputes: docs.stripe.com/disputes.
• Adyen refunds: docs.adyen.com/online-payments/refund; disputes: docs.adyen.com/risk-management/disputes-api.
• PayPal Captures.refund: developer.paypal.com/docs/api/payments/v2/#captures_refund; Customer Disputes: developer.paypal.com/docs/api/customer-disputes/v1/.
• Reason codes (Visa / Mastercard tables): references/reason-codes.md.
• Replay simulators + signature gauntlet: references/replay-simulators.md.
• Advanced recovery scenarios: references/advanced-recovery-scenarios.md.
• State model: payment-flow-states-reference.
• Sandboxes: payment-gateway-sandboxes, stripe-test-cards-and-webhooks.
• Generic webhook receiver testing: webhook-delivery-tester (qa-notifications).