Merchant payment receipts

The sandbox merchant receipt routes are disabled by default. Set FUTA_MERCHANT_RECEIPTS_ENABLED=true on both the switch and merchant API to enable this local component. This does not enable real providers or establish production readiness.

Use GET /v1/payments/{id}/receipt.pdf?lang=fr with an API key that has payments:read. The team equivalent is GET /portal/merchants/{merchantId}/payments/{id}/receipt.pdf?lang=en, using the current merchant MFA token and X-Futa-Membership-Version. The team route checks live membership, version and permissions. Both share the merchant request quota. Omit lang for French; only literal fr and en are accepted, with no other query parameters or request body.

First inspect the payment obligation and choose its collected_payment_id. A receipt always names the exact requested payment and its original obligation. A declined original returns 409 RECEIPT_NOT_APPROVED; it is never silently replaced with its successful child. A foreign or missing payment returns 404 for an otherwise authorized API key. Missing approval or posting evidence, invalid upstream data and upstream outages fail closed with 503.

The PDF contains the original amount, currency, merchant and payment references, immutable creation/approval times, and a separately labeled snapshot of completed refunds. A refund does not rewrite the original payment amount. The synthetic payer fee is zero. The receipt contains no checkout or account capability and explicitly states that it does not prove a real transfer.

Successful downloads use application/pdf, a safe attachment filename, Cache-Control: no-store, Referrer-Policy: no-referrer and X-Content-Type-Options: nosniff. Keep the downloaded file private. The API reads a strict, bounded, capability-free switch projection with a five-second deadline and no automatic retry or redirect.

Keep the PDF’s bytes exactly as the response carries them. Futa’s generated TypeScript client, kept for its own use and not published, reads them with PaymentsApi.downloadPaymentReceipt and MerchantTeamsApi.downloadTeamPaymentReceipt as a Blob. Handle 401/403 by restoring access, 409 by refreshing the current membership or selecting the actual collected attempt, and 503 as unavailable; do not create a new payment to recover a download.