Troubleshooting

Use the database and the provider dashboard together. The success page in the browser is not evidence that a payment or an approval happened.

The customer paid and the booking is still pending payment

The redirect arrived and the webhook did not, or the signature check failed.

1. Read orders.status and payments.status.
2. Look for a payment_webhook_events row for that provider event id.
3. If the event is absent, inspect API logs for a signature failure.
4. Run reconcile so the API reads the provider payment and applies the normal transaction.
5. Confirm the webhook URL is the public Express route and the signing secret matches the endpoint.

The booking is pending approval and the customer expects a confirmed date

That is the intended state after a verified payment. The photographer still has to approve or reject it. Check bookings.status and the photographer notification. Do not update the status with a manual SQL statement. Use the decision endpoint so the audit row and any reward credit are written together.

A refund did not appear

1. Confirm the booking is REJECTED or CANCELLED and the order is REFUND_PENDING or REFUNDED.
2. Read the payment.refund job. FAILED jobs keep last_error.
3. Match payments.provider_payment_id to the provider refund.
4. A duplicate refund call should be refused by the provider idempotency key stored with the payment. Do not create a second full refund by hand unless the provider shows that no refund exists.

The customer cannot download a published gallery

Publication is not access. Check publication_status, access_status, and photos.status.

Observed	Result
Published, access pending	No signed URL. Approve access.
Approved, photo still PROCESSING	No signed URL until the thumbnail job sets READY.
Access revoked	No new URL. An older URL works only until its five-minute expiry.
Another customer's access token	Not found.

A referral discount is missing

1. Confirm the reward is AVAILABLE and a positive CREDIT exists. PENDING is not spendable.
2. Sum reward_ledger.amount_cents for the referrer. That sum is the balance.
3. A self-referral or a second referrer never creates a second row. referrals.referred_user_id is unique.
4. If the qualifying booking was rejected, the reward should be REVERSED or still PENDING with no credit.

A ledger row looks wrong

Do not update it. Insert a REVERSAL through the refund or an audited administrative reversal that uses the same sign rules. The database rejects UPDATE and DELETE on reward_ledger.

Jobs are stuck

Claimed jobs have locked_at set and status RUNNING. A worker that died leaves that lock. The worker releases locks older than its heartbeat before claiming again. Inspect attempt_count and last_error. Email and thumbnail failures do not roll back the booking or the original file.