# ADR-004: Payment provider and idempotent payment calls

- Status: Accepted
- Date: 2024-06-10
- Decided by: Imogen Varga, with Hana Sato

## Context

Ferrylog takes card payments for operators. The payment provider confirms results by calling our
webhook, and it retries a webhook until we acknowledge it. Our own calls to the provider can also time
out after the provider has acted on them. Without care, a retry on either side can charge a passenger
twice or settle the same booking twice.

## Decision

We use Larchpay as the payment provider, chosen for its per-request idempotency keys and its webhook
signatures.

Every charge, capture and refund request carries an idempotency key derived from the booking and the
action, so repeating a request returns the original result instead of acting again. Webhooks are
verified by signature and recorded in the `payment_event` table with a unique constraint on the
provider's event identifier, so a retried webhook is acknowledged without being processed twice.
A payment in progress marks its seat hold (ADR-002) so the sweeper leaves it alone.

## Consequences

- Retrying a payment call is always safe, which the payment webhook runbook relies on.
- Changing provider later means reproducing this behaviour; it is the main lock-in we accept.
- Engineers must never call the provider without an idempotency key; code review checks this.
