This guide is for developers who want to print or show the receipt WinkPG keeps for a transaction: a terminal application that prints a copy at the counter, or an online checkout that shows the receipt again later. It covers how receipts are generated, the four receipt requests, and what a receipt does and doesn't contain.

What a receipt is

A receipt records one event in a transaction's life, such as the authorization, the capture, or a refund, exactly as it stood at that moment. It never changes after it's generated. A transaction can have several receipts, one for each event, numbered in the order they were generated.

Every receipt has a type:

WinkPG generates the receipt for each event in the background, shortly after the event. A transaction you've just created can therefore have no receipt yet. The transaction's receiptIds lists the receipts it has, oldest first.

The requests

Every receipt request names the merchant and the transaction in the path, in the same way as the follow-up operations on a transaction.

The three GET requests need an API key with the transactions:read scope. The POST needs transactions:write, because it can store a new receipt.

A receipt that belongs to another merchant, or to another transaction of the same merchant, returns HTTP 404, the same as a receipt id that doesn't exist. Always address a receipt under the transaction it belongs to.

List a transaction's receipts

The list returns a summary of each receipt: its id, receiptType, sequenceNumber, generatedAtUtc, whether the transaction was approved, the total, and whether the receipt has been emailed.

An empty list isn't an error. It means no receipt has been generated yet. If you need the receipt now, request it with the POST described in Get a receipt on demand instead of polling the list.

Read a receipt

Read one receipt as JSON when your application lays out its own printout. The response carries what's printed on the gateway's receipt: the merchant's name, address, and terminal ID, the status and authorization code, the amounts, the payment method, any custom fields the merchant shows on receipts, and the dates.

statusDisplay is one of Approved, Partially Approved, Pending, Not Completed, or Declined. authorizationCode is present only on an approved receipt.

Print the gateway's receipt

The /html request returns the receipt WinkPG renders for email and the payment pages, as a complete HTML document with inline styles. Send it to a printer or show it in a web view as it is.

The response is served with a Content-Security-Policy that sandboxes the document: it can't run script, and it can load only its own styles and images. If you show it inside your own page, put it in a sandboxed iframe rather than inserting the markup into the page.

Get a receipt on demand

When the terminal needs to print before the background receipt exists, ask for it directly:

POST /api/transactions/by-merchant/{merchantId}/{transactionId}/receipts
Content-Type: application/json

{
  "receiptType": "Authorization"
}

The response is the receipt, in the same shape as the single-receipt GET. The request is safe to repeat:

• A type the transaction already has returns that receipt. Asking for Authorization twice returns the same receipt id both times, and so does asking after the background receipt was generated.
• OnDemand returns the most recent receipt when it's also an on-demand copy, so a retry doesn't make a second copy. Asking again after another receipt was generated makes a new copy.
• SplitTenderSummary can't be requested. WinkPG generates it once the whole split tender group completes, and the request returns HTTP 400.

receiptType is required. A request without it returns HTTP 400.

What a receipt never contains

A receipt identifies a card by its brand and last four digits only. It never carries the full card number, the expiration date, the security code, or a payment token, in the JSON or in the HTML. That makes a receipt safe to print, email, and keep in your own records.

See also

• Card-present payments over the API for the sale request a terminal sends before it prints.
• Refunds, voids, and reversals for the operations that produce refund, void, and reversal receipts.
• Transaction lifecycle and settlement for the events a transaction moves through.