diff --git a/mintlify/docs.json b/mintlify/docs.json index 5bc96138..b3d25638 100644 --- a/mintlify/docs.json +++ b/mintlify/docs.json @@ -141,6 +141,7 @@ "payouts-and-b2b/depositing-funds/depositing-funds", "payouts-and-b2b/payment-flow/send-payment", "payouts-and-b2b/payment-flow/list-transactions", + "payouts-and-b2b/payment-flow/receipts", "payouts-and-b2b/payment-flow/reconciliation", "payouts-and-b2b/payment-flow/error-handling" ] diff --git a/mintlify/payouts-and-b2b/payment-flow/receipts.mdx b/mintlify/payouts-and-b2b/payment-flow/receipts.mdx new file mode 100644 index 00000000..d6efb77f --- /dev/null +++ b/mintlify/payouts-and-b2b/payment-flow/receipts.mdx @@ -0,0 +1,10 @@ +--- +title: "Receipts" +description: "Send a compliant receipt to your customer for every completed transaction" +icon: "/images/icons/receipt-check.svg" +"og:image": "/images/og/og-payouts-b2b.png" +--- + +import Receipts from '/snippets/receipts.mdx' + + diff --git a/mintlify/snippets/receipts.mdx b/mintlify/snippets/receipts.mdx new file mode 100644 index 00000000..84a0c057 --- /dev/null +++ b/mintlify/snippets/receipts.mdx @@ -0,0 +1,264 @@ +export const ReceiptExample = () => { + const mono = "ui-monospace, 'SF Mono', SFMono-Regular, Menlo, Consolas, monospace"; + const hair = '0.5px solid rgba(38,38,35,0.1)'; + const hairLight = '1px solid rgba(38,38,35,0.07)'; + const secLabel = { fontFamily: mono, fontSize: '10px', letterSpacing: '0.08em', textTransform: 'uppercase', color: '#989898' }; + const secLabelHeading = { fontFamily: mono, fontSize: '10px', letterSpacing: '0.08em', textTransform: 'uppercase', color: '#989898', paddingBottom: '8px' }; + const secLabelMb = { fontFamily: mono, fontSize: '10px', letterSpacing: '0.08em', textTransform: 'uppercase', color: '#989898', marginBottom: '6px' }; + const rowLabel = { fontSize: '13px', color: '#7c7c7c' }; + const subLabelMb = { fontSize: '13px', color: '#7c7c7c', marginBottom: '5px' }; + const monoVal = { fontFamily: mono, fontSize: '14px', color: '#1a1a1a' }; + const amounts = [ + ['Transfer Amount', '$500.00'], + ['Total to Recipient', '$500.00'], + ['Taxes', '$0.00'], + ['Total Transfer Fees', '$2.50'], + ]; + return ( +
+
+ +
+
+ + Lightspark +
+
+ + + Completed + + 06 / 10 / 2026
14:32:08 PDT
+
+
+ +
+ Lightspark Payments, LLC  ·  NMLS ID 2429193 + 8605 Santa Monica Blvd, PMB 64461, West Hollywood, CA 90069 + www.lightspark.com  ·  (855) 516-0103 +
+ +
+
+ Total charged + + $502.50 + USD + +
+ +
+ Total received + + 500.00 + USDC + +
+
+ +
+
+
+
Sender
+
Marcus Chen
+
+
+
Recipient
+
Sofía Herrera
+
+
+
+ Transaction ID + 019542f5-b3e7-1d02-0000-000000000030 +
+
+ +
+
On-chain details
+
+
Transaction Hash
+
0x8f3a4c2e91b07d6f5a8e2c4b9d1f0a73e6c5b8d2f4a1e9c7b3d0f6a2e8c4b1d9
+
+
+
VC Address(es)
+
From  0x6A2e8C4b1D9f3A4c2E91b07d6F5a8E2c4B9d1F0a
To      0x4B9d1F0a73E6c5B8d2F4a1E9c7b3D0f6A2e8C4b1
+
+
+ +
+
Amounts
+ {amounts.map((row) => ( +
+ {row[0]} + {row[1]} +
+ ))} +
+ Total + $502.50 +
+
+ Exchange Rate + 1 USDC = 1.00 USD +
+
+ +
+

To report fraud or suspected fraud in connection with the money transmission services, please call customer service toll-free at (855) 516-0103.

+

Lightspark Payments, LLC is liable for nondelivery or delayed delivery.

+
+
Refund Policy
+

You may cancel for a full refund within 30 minutes of payment, unless the funds have already been picked up or deposited. Refund requests can be made at www.lightspark.com/refunds or by calling the number above.

+
+

Recipient may receive less than the total to recipient due to fees charged by the recipient's bank and any foreign taxes. (Foreign remittance only.)

+
+ +
+
+ ); +}; + +If you're an **unregulated platform** moving funds using Grid's money transmitter licenses, Grid (operating as Lightspark Payments, LLC) is the licensed money transmitter on your transactions. That license requires a receipt to be delivered to the customer for every completed transaction. Because you own the customer relationship, at the end of each transaction you'll need to deliver the transaction receipt. + +This guide explains when to send a receipt, what it must contain, how to map Grid transaction data to each receipt field, and how to confirm delivery back to Grid. + + +Receipts are **required for regulatory compliance** — they're not an optional best practice. Send a receipt to your customer for **every** completed transaction, and confirm delivery to Grid. Your platform agreement obligates you to deliver receipts and to furnish records of delivery on request. + + +## Sample receipt layout + +Your receipt's visual design is up to you, but the content and field set are fixed. The layout below shows an example with sample data filled in: + + + +## When to send a receipt + +Trigger receipt generation off the transaction completion event: + +- **`OUTGOING_PAYMENT.COMPLETED`** — a send (the customer is the sender). +- **`INCOMING_PAYMENT.COMPLETED`** — a receive (the customer is the recipient). + +Send the receipt to your customer as soon as the transaction completes — by email, in-app notification, or any channel that lets the customer **retain** the receipt (for example, a downloadable PDF or an email they can save). + + +Only completed transactions get a receipt. Transactions that end in `FAILED` or `EXPIRED` do not. Once you send a receipt, **freeze its contents** — if the transaction is later reversed or refunded, the original receipt stays as issued and the reversal is tracked separately on the transaction record. + + +## What a receipt must contain + +A compliant receipt combines **Lightspark's regulatory disclosures** (fixed values and legal language) with **data-driven fields** populated from the specific transaction. + +### Lightspark regulatory disclosures + +Include these exactly as written on every receipt: + +| Field | Value | +|-------|-------| +| Money transmitter | Lightspark Payments, LLC | +| NMLS ID | 2429193 | +| Regulatory address | 8605 Santa Monica Blvd, PMB 64461, West Hollywood, CA 90069 | +| Website | www.lightspark.com | +| Customer service phone | (855) 516-0103 | +| Fraud reporting | "To report fraud or suspected fraud in connection with the money transmission services, please call customer services toll-free at (855) 516-0103." | +| Nondelivery liability | "Lightspark Payments, LLC is liable for nondelivery or delayed delivery." | +| Refund policy | Lightspark's refund policy for transmitted funds (link or full text). | + +### Transaction fields + +| Field | Description | Required when | +|-------|-------------|---------------| +| Sender | Name of the customer initiating the transaction | Always | +| Recipient | Name of the recipient receiving funds | Always | +| Transaction ID | Unique ID per transaction | Always | +| Transaction type | Cross-border send/receive, on-ramp, off-ramp, or transfer out; for virtual currency transactions, the currency type | Always | +| Transaction date | Date the transaction was funded | Always | +| Transaction time | Precise time including time zone | Always | +| Transfer amount | Amount in the currency the transmission was funded in | Always | +| Total to recipient | Amount in the currency the recipient receives | Always | +| Total transfer fees | All fees charged in connection with the transaction | Always | +| Taxes | Itemized taxes | When taxes apply | +| Total | Total cost to the sender | Always | +| Exchange rate | FX rate applied, rounded to 2–4 decimal places | When the funding and receiving currencies differ | +| Transaction hash | On-chain transaction hash | Crypto transactions only | +| Virtual currency address(es) | Public on-chain addresses involved | Crypto transactions only | +| FX shortfall disclosure | "Recipient may receive less due to fees charged by the recipient's bank and foreign taxes." | Foreign remittance transactions only | + +## Mapping Grid data to receipt fields + +Most receipt fields come directly from the [transaction object](/api-reference/transactions/get-transaction-by-id) — available on the completion webhook payload or by retrieving the transaction. All amounts are integers in the smallest unit of their currency (for example, cents), so format them using the currency's `decimals`. + +| Receipt field | Grid source | +|---------------|-------------| +| Transaction ID | `id` | +| Transaction type | `type` (`OUTGOING` / `INCOMING`) plus the funding currency | +| Transaction date / time | `settledAt` | +| Sender | `customerId` / `platformCustomerId` (outgoing) or `counterpartyInformation` (incoming) | +| Recipient | Destination external account beneficiary — resolve `destination.accountId` to the external account and use its beneficiary (from `accountInfo`) or `customerId` (outgoing); `customerId` / `platformCustomerId` (incoming) | +| Transfer amount | `sentAmount.amount` + `sentAmount.currency` | +| Total to recipient | `receivedAmount.amount` + `receivedAmount.currency` | +| Total transfer fees | `fees` (smallest unit of the sending currency) | +| Exchange rate | `exchangeRate` | +| Transaction hash / VC address(es) | `reconciliationInstructions.transactionHash` (a dedicated transaction hash field may be exposed directly on the transaction) | + +## Example: send a receipt on completion + +Listen for the completion webhook, verify its signature, assemble the receipt fields, and send the receipt to your customer. See [Webhooks](/payouts-and-b2b/platform-tools/webhooks) for signature verification. + +```javascript +// Inside your verified webhook handler +app.post('/webhooks/grid', async (req, res) => { + // ... verify the X-Grid-Signature header first (see Webhooks) ... + + const event = req.body; + if (event.type === 'OUTGOING_PAYMENT.COMPLETED' || + event.type === 'INCOMING_PAYMENT.COMPLETED') { + const tx = event.data; + + const format = (money) => + (money.amount / 10 ** money.currency.decimals).toFixed(money.currency.decimals); + + const receipt = { + // Lightspark regulatory disclosures (fixed) + moneyTransmitter: 'Lightspark Payments, LLC', + nmlsId: '2429193', + address: '8605 Santa Monica Blvd, PMB 64461, West Hollywood, CA 90069', + customerServicePhone: '(855) 516-0103', + // Transaction fields + transactionId: tx.id, + transactionType: tx.type, + transactionDateTime: tx.settledAt, + transferAmount: `${tx.sentAmount.currency.symbol}${format(tx.sentAmount)}`, + totalToRecipient: `${tx.receivedAmount.currency.symbol}${format(tx.receivedAmount)}`, + totalTransferFees: tx.fees, + exchangeRate: tx.exchangeRate, // include when currencies differ + }; + + await sendReceiptEmail(tx.platformCustomerId, receipt); // your delivery channel + + // Tell Grid the receipt was delivered + await confirmReceiptDelivery(tx.id); + } + + res.status(200).json({ received: true }); +}); +``` + +## Confirm delivery to Grid + +After you deliver the receipt to your customer, confirm it with the [Confirm receipt delivery](/api-reference/transactions/confirm-receipt-delivery) endpoint. Grid stores the confirmation timestamp on the transaction's `receiptDeliveryConfirmedAt` field so it can be furnished to regulators on request. + +```bash cURL +curl -X POST 'https://api.lightspark.com/grid/2025-10-13/transactions/{transactionId}/confirm' \ + -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \ + -H 'Content-Type: application/json' \ + -d '{ "receiptDeliveryConfirmedAt": "2025-10-03T15:31:00Z" }' +``` + + +`receiptDeliveryConfirmedAt` is optional — if you omit it, Grid records the current server time. Calling the endpoint again for the same transaction updates the stored confirmation time. +