Receipts
Bead payment methods require a small number of fields beyond what you already include on a standard card receipt. This page covers what's required, what's additionally available, and how delivery works.
Required fields
The following fields must be included on all Bead payment receipts when applicable:
Payment method
Always
amounts.paid.inPaymentCurrency.currency.name on GET /Payments/{id} (e.g. Bitcoin Lightning)
Final payment status
Always
statusCode on the payment object
Exchange rate
When a crypto-to-fiat conversion occurs
conversions[].executedExchangeRate on GET /Payments/{id}
The conversions[] array is present on completed crypto payments. Check that conversions is non-empty before attempting to read the exchange rate — it will not be present on card-only payments.
Fields your existing receipt already covers — date, time, amount, merchant name, taxes, support contact — do not need to change.
Additional fields available
The following fields are available from GET /Payments/{id} and are useful to include on receipts for crypto payments, but are not required by Bead.
Payment code
paymentCode
Unique identifier for the payment
Payment date/time
receivedTime
ISO 8601 timestamp
Crypto amount paid
amounts.paid.inPaymentCurrency.amount
Amount in the payment currency
Crypto asset
amounts.paid.inPaymentCurrency.currency.code
e.g. BTC
Requested fiat amount
amounts.requested.inRequestedCurrency.amount
The amount the merchant requested
Requested fiat currency
amounts.requested.inRequestedCurrency.currency.code
e.g. USD
When to issue the receipt
Generate or finalize the receipt after the payment reaches a final state. All fields above are available from a single call: GET /Payments/{id}. The payment result webhook also includes conversions[], so you can read the exchange rate directly from the webhook payload without a follow-up GET call. See Payment Statuses for the complete list of final states.
Receipt delivery
Integrator-delivered (default): You deliver the receipt to the consumer using your existing channels — printed, email, SMS, in-app, or portal.
Bead-delivered (optional): Enable emailReceipt and/or smsReceipt on the Create Payment request to have Bead send the receipt directly to the consumer. When enabled, you do not need to send a separate consumer receipt. You remain responsible for merchant-side records, back-office retrievability, and retaining receipt records and delivery evidence for at least 7 years.
Retention
Retain receipts and evidence of delivery or access for at least 7 years and make them available on request for audit or regulatory review.
Last updated