PII (Payment Incident Investigator)

• 

• 

• 

• 

• 

• 

• 

• 

• 

• 

• 

• 

• 

• 

• 

• 

• 

• 

• 

Inspiration

A customer says, “I paid,” but the merchant’s store still shows “Payment pending.”

Resolving that disagreement can mean checking payment records, application logs, webhook deliveries and fulfillment systems. A payment may have succeeded even when the merchant’s application timed out. Retrying the wrong operation can make the situation worse.

We wanted to help merchant teams answer three questions: What actually happened? What evidence supports that conclusion? What can we safely do next?

That became PII—Payment Incident Investigator.

What it does

PII is a web application for merchant teams operating a custom PayPal checkout. It connects payment evidence with the merchant’s order and fulfillment records to investigate inconsistencies.

For each case, PII is designed to:

• Display payment, order and fulfillment states separately.
• Build a timeline linking provider records, verified webhooks and application events.
• Explain confirmed facts, possible causes and missing evidence.
• Present a bounded recovery action for an authorized person to approve.
• Record execution and verify the resulting state.

For example, when payment is confirmed but the store failed to update an order, PII can propose resuming its fulfillment workflow. Repeated requests must reuse the same recovery operation to prevent duplicate effects.

The AI explains and proposes. A human approves. Deterministic backend checks control execution.

How we built it

We designed PII around separate responsibilities: evidence collection, investigation, approval and recovery.

The proposed implementation uses React and TypeScript for the interface, a Node.js backend, PostgreSQL for durable records, and a background worker for recovery operations.

PayPal Orders and Payments APIs supply current payment facts. Verified webhooks provide event evidence, while a merchant adapter supplies local order and fulfillment records.

The language model receives sanitized evidence and returns structured explanations with references to supporting records. It has no payment or recovery write tools.

The MVP targets one sandbox merchant and one demo store, with controlled application failures clearly distinguished from genuine sandbox payment evidence.

Challenges we ran into

The hardest design challenge was handling uncertainty correctly. A timeout does not prove that a payment failed, and buyer approval does not prove that payment was captured.

Other challenges included duplicate events, missing identifiers, stale approvals and a worker crashing after an action succeeds.

We also needed to prevent plausible AI explanations from becoming unsupported conclusions. PII therefore separates verified facts from hypotheses and keeps recovery eligibility outside the model.

Accomplishments that we're proud of

We turned a broad troubleshooting idea into a defined, reviewable workflow.

Our strongest design decisions are evidence-linked explanations, approval tied to an exact action, and recovery records that preserve the same operation across retries.

We also defined failure scenarios and acceptance criteria before making performance or reliability claims.

What we learned

Payment correctness depends on coordination between systems. A successful payment and a successfully fulfilled order are separate facts.

We learned that uncertainty must remain visible, that identifiers matter more than superficial matches, and that useful AI should help operators assess evidence without replacing their authority.

What's next for PII (Payment Incident Investigator)

Our next steps are to complete and evaluate the sandbox workflow, compare it against manual investigation and a deterministic reconciliation baseline, and test anonymized incidents with merchant developers.

We will measure decision correctness, investigation time, unsafe proposals and duplicate effects under controlled failures.

Further development will focus on merchant adapters, better evidence collection and authorized read-only pilots before enabling production recovery.

Built With

• node.js
• paypal
• paypal-rest-api
• paypal-sandbox
• postgresql
• react
• typescript