# Receipts

Send payment receipts to customers by email or SMS, render a printable receipt, and download a PDF receipt.

All `/api/v1/notifications/*` endpoints are admin API calls: send `Authorization: Bearer <JWT>` (or an API key in `x-api-key`). The tenant comes from the token or key. Responses use the standard `{ "success": true, "data": ... }` envelope; validation failures return `400` with `{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "..." } }`.

> **Identifying the transaction:** the send endpoints accept either a full `transaction` object or a `transactionId`. `transactionId` is the transaction's **`transactionId` field** (the reference shown on receipts, e.g. `TXN-1768489200000-7F3A9C21`), not its UUID `id`. Sending neither returns `400`; a `transactionId` that does not exist in your tenant currently returns `500 INTERNAL_ERROR`.

---

## Send Email Receipt

```http
POST /api/v1/notifications/receipt/email
```

```bash
curl -X POST https://uat.auxcore.net/api/v1/notifications/receipt/email \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "TXN-1768489200000-7F3A9C21",
    "email": "customer@example.com"
  }'
```

| Field | Type | Required | Notes |
|---|---|---|---|
| `transactionId` | string | one of `transactionId` / `transaction` | Looked up within your tenant. |
| `transaction` | object | one of `transactionId` / `transaction` | A full transaction object; used as-is instead of a lookup. |
| `email` | string | yes | Must be a valid email address. |
| `merchantId` | string (UUID) | no | Merchant whose branding is used; defaults to the transaction's merchant. |
| `merchantLogo` | string (URL) | no | Overrides the merchant's branding logo. |
| `merchantInfo` | object | no | `{ "companyName": "...", "merchantId": "..." }` — overrides the business name shown. |

The receipt uses the merchant's branding (logo, primary color, address, receipt header/footer) and formats times in the location's timezone. For approved transactions a copy is also sent to the merchant's notification email.

When the transaction was sold with a cart (`lineItems`, see [Transactions](../core/transactions.md), "Itemised sale"), the email adds an **Order Summary** listing each item — name, quantity with unit, unit price and line total. The printed receipt (`/receipt/print`, when no `invoice.lineItems` are passed) and the PDF receipt list them too. The SMS receipt does not.

**Response:**
```json
{
  "success": true,
  "message": "Email receipt sent successfully",
  "data": {
    "messageId": "<0f8e1c2a-5b7d-4e1f-9c3a-2d6b8e4f1a7c@auxcore.net>"
  }
}
```

---

## Send SMS Receipt

```http
POST /api/v1/notifications/receipt/sms
```

```bash
curl -X POST https://uat.auxcore.net/api/v1/notifications/receipt/sms \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "TXN-1768489200000-7F3A9C21",
    "phoneNumber": "+15555550123",
    "includePDF": true
  }'
```

| Field | Type | Required | Notes |
|---|---|---|---|
| `transactionId` / `transaction` | string / object | one of them | Same as the email receipt. |
| `phoneNumber` | string | yes | Must be a valid phone number (E.164 recommended). |
| `merchantId` | string (UUID) | no | Used for branding and timezone; defaults to the transaction's merchant. |
| `includePDF` | boolean | no | When `true`, a PDF receipt is generated and sent with the message. If PDF generation fails, the text receipt is still sent (`hasPDF: false`). |

**Response:**
```json
{
  "success": true,
  "message": "SMS receipt sent successfully",
  "data": {
    "messageId": "SM1f2e3d4c5b6a79881726354453627181",
    "provider": "twilio",
    "hasPDF": true,
    "logId": "6c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
  }
}
```

---

## Refund Receipts

```http
POST /api/v1/notifications/receipt/refund/email
```

A refund receipt has its own endpoints: `POST /api/v1/notifications/receipt/refund/email` (body: `refund`, `transaction`, `email`, optional `merchantId`) and `POST /api/v1/notifications/receipt/refund/sms` (body: `refund`, `transaction`, `phoneNumber`, optional `merchantId`, `includePDF`). Both `refund` and `transaction` must be full objects (there is no `transactionId` lookup); `refund.amount` below `transaction.amount` is shown as a partial refund.

---

## Generate Print Receipt

```http
POST /api/v1/notifications/receipt/print
```

Returns a print-ready HTML receipt (for a browser print dialog or a receipt printer).

```bash
curl -X POST https://uat.auxcore.net/api/v1/notifications/receipt/print \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "transactionId": "TXN-1768489200000-7F3A9C21" }'
```

Body: `transactionId` or `transaction` (required), optional `merchantLogo`, `title`, `invoice`.

**Response:**
```json
{
  "success": true,
  "data": { "html": "<!DOCTYPE html><html>...</html>" }
}
```

---

## Download PDF Receipt

```http
GET /api/v1/notifications/receipts/:transactionId/pdf
```

```bash
curl https://uat.auxcore.net/api/v1/notifications/receipts/TXN-1768489200000-7F3A9C21/pdf \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o receipt.pdf
```

`:transactionId` accepts the transaction's UUID `id` or its `transactionId`. The lookup applies your merchant scope, so a merchant user can only download its own receipts. Returns `application/pdf` (`Content-Disposition: attachment; filename="receipt-<transactionId>.pdf"`), or `500 INTERNAL_ERROR` on failure. An unknown `:transactionId` currently also returns `500` (the `404 NOT_FOUND` branch is only hit when the transaction has no merchant).

---

## Public PDF Receipt

```http
POST /api/v1/public/receipt-pdf
```

Generates the same PDF receipt from the public API surface. It needs **no API key**; the tenant is taken from the `X-Tenant-ID` header (or a `tenantId` body field).

```bash
curl -X POST https://uat.auxcore.net/api/v1/public/receipt-pdf \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{ "transactionId": "TXN-1768489200000-7F3A9C21" }' \
  -o receipt.pdf
```

| Field | Type | Required | Notes |
|---|---|---|---|
| `transactionId` | string | yes | The transaction's `transactionId`. The PDF is always rendered from the stored transaction; other receipt fields in the body are ignored. |
| `tenantId` | string | no | Used only when the `X-Tenant-ID` header is absent. |

Returns `application/pdf`. Any failure (including an unknown transaction) returns `500` with `{ "success": false, "error": "Failed to generate receipt PDF" }`.

---

## Customize the Receipt

There is no per-request template parameter. Receipt appearance comes from the merchant's branding settings in the portal: logo, primary color, business address, and the receipt header and footer text. Times are rendered in the timezone of the location (branch) that took the payment, falling back to the merchant's timezone.

---

**Need help?** Contact support@auxcore.net