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#

POST/api/v1/notifications/receipt/email

Send Email Receiptbash

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, "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:

Send Email Receiptjson

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

Send SMS Receipt#

POST/api/v1/notifications/receipt/sms

Send SMS Receiptbash

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:

Send SMS Receiptjson

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

Refund Receipts#

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#

POST/api/v1/notifications/receipt/print

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

Generate Print Receiptbash

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:

Generate Print Receiptjson

{
  "success": true,
  "data": { "html": "<!DOCTYPE html><html>...</html>" }
}

Download PDF Receipt#

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

Download PDF Receiptbash

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#

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).

Public PDF Receiptbash

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