# POST /api/transactions/by-merchant/{merchantId}/{transactionId}/receipts Get or generate a transaction receipt. Returns the transaction's receipt of the requested type, generating it first when the transaction doesn't have one yet. Use it when the receipt list is still empty and the receipt is needed now. For a type a transaction has once, such as `Authorization`, sending the request again returns the same receipt. `OnDemand` returns the same copy for an immediate retry, and generates a new copy once another receipt has been generated since. **Operation ID:** `transactionReceiptsGenerate` ## Authorization Requires: Transactions.Receipts.Create, merchant scope. Requires API key scope: `transactions:write` Required permissions: - `Transactions.Receipts.Create` ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | merchantId | path | yes | string(uuid) | The merchant that owns the transaction. | | transactionId | path | yes | string(uuid) | The transaction to produce the receipt for. | | suppressNulls | query | no | boolean | If true, omit properties with null values. | ## Request Body The receipt type. **Content type:** `application/json` Schema: [`GenerateTransactionReceiptInput`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/GenerateTransactionReceiptInput.md) Properties: - `receiptType` ([ReceiptType](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ReceiptType.md)) required: The event to produce the receipt for. When the transaction already has a receipt of this type, that receipt is returned and no new one is generated. `OnDemand` returns the most recent receipt when it is also an on-demand one, and generates a new copy otherwise. `SplitTenderSummary` is not accepted: the summary is generated once the whole group completes. (nullable) Values: - `Authorization`: Receipt generated after a successful authorization. - `Capture`: Receipt generated after a capture/settlement. - `Refund`: Receipt generated after a full refund. - `PartialRefund`: Receipt generated after a partial refund. Multiple partial refund receipts may exist on a single transaction, each with a distinct sequence number. - `Void`: Receipt generated after a void. - `Reversal`: Receipt generated after a full reversal: the entire approved amount has been released back to the issuer. Distinguished from PartialReversal so the transaction-detail / explorer pages can show the lifecycle event clearly. - `OnDemand`: Receipt generated on-demand from the UI (legacy/fallback for pre-module transactions). - `PartialReversal`: Receipt generated after a partial reversal. Multiple partial reversal receipts may exist on a single transaction (one per reversal operation), each with a distinct sequence number. - `SplitTenderSummary`: Summary receipt for a completed split tender group: the order total, what each tender in the group authorized, and the combined authorized amount. Generated once per group, after the final tender completes, in addition to the per-tender receipts. _Example: Receipt for an approved sale_ Returns the authorization receipt of an approved sale or authorization, generating it if it hasn't been generated yet. Put the transaction id in the route as transactionId. Sending the same request again returns the same receipt id. ```json { "receiptType": "Authorization" } ``` _Example: On-demand copy_ Generates an on-demand copy of the transaction's receipt, for a reprint. Put the transaction id in the route as transactionId. A retry of the same request returns the copy it just generated rather than a second one. ```json { "receiptType": "OnDemand" } ``` **Content type:** `text/json` Schema: [`GenerateTransactionReceiptInput`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/GenerateTransactionReceiptInput.md) Properties: - `receiptType` ([ReceiptType](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ReceiptType.md)) required: The event to produce the receipt for. When the transaction already has a receipt of this type, that receipt is returned and no new one is generated. `OnDemand` returns the most recent receipt when it is also an on-demand one, and generates a new copy otherwise. `SplitTenderSummary` is not accepted: the summary is generated once the whole group completes. (nullable) Values: - `Authorization`: Receipt generated after a successful authorization. - `Capture`: Receipt generated after a capture/settlement. - `Refund`: Receipt generated after a full refund. - `PartialRefund`: Receipt generated after a partial refund. Multiple partial refund receipts may exist on a single transaction, each with a distinct sequence number. - `Void`: Receipt generated after a void. - `Reversal`: Receipt generated after a full reversal: the entire approved amount has been released back to the issuer. Distinguished from PartialReversal so the transaction-detail / explorer pages can show the lifecycle event clearly. - `OnDemand`: Receipt generated on-demand from the UI (legacy/fallback for pre-module transactions). - `PartialReversal`: Receipt generated after a partial reversal. Multiple partial reversal receipts may exist on a single transaction (one per reversal operation), each with a distinct sequence number. - `SplitTenderSummary`: Summary receipt for a completed split tender group: the order total, what each tender in the group authorized, and the combined authorized amount. Generated once per group, after the final tender completes, in addition to the per-tender receipts. _Example: Receipt for an approved sale_ Returns the authorization receipt of an approved sale or authorization, generating it if it hasn't been generated yet. Put the transaction id in the route as transactionId. Sending the same request again returns the same receipt id. ```json { "receiptType": "Authorization" } ``` _Example: On-demand copy_ Generates an on-demand copy of the transaction's receipt, for a reprint. Put the transaction id in the route as transactionId. A retry of the same request returns the copy it just generated rather than a second one. ```json { "receiptType": "OnDemand" } ``` **Content type:** `application/*+json` Schema: [`GenerateTransactionReceiptInput`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/GenerateTransactionReceiptInput.md) Properties: - `receiptType` ([ReceiptType](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ReceiptType.md)) required: The event to produce the receipt for. When the transaction already has a receipt of this type, that receipt is returned and no new one is generated. `OnDemand` returns the most recent receipt when it is also an on-demand one, and generates a new copy otherwise. `SplitTenderSummary` is not accepted: the summary is generated once the whole group completes. (nullable) Values: - `Authorization`: Receipt generated after a successful authorization. - `Capture`: Receipt generated after a capture/settlement. - `Refund`: Receipt generated after a full refund. - `PartialRefund`: Receipt generated after a partial refund. Multiple partial refund receipts may exist on a single transaction, each with a distinct sequence number. - `Void`: Receipt generated after a void. - `Reversal`: Receipt generated after a full reversal: the entire approved amount has been released back to the issuer. Distinguished from PartialReversal so the transaction-detail / explorer pages can show the lifecycle event clearly. - `OnDemand`: Receipt generated on-demand from the UI (legacy/fallback for pre-module transactions). - `PartialReversal`: Receipt generated after a partial reversal. Multiple partial reversal receipts may exist on a single transaction (one per reversal operation), each with a distinct sequence number. - `SplitTenderSummary`: Summary receipt for a completed split tender group: the order total, what each tender in the group authorized, and the combined authorized amount. Generated once per group, after the final tender completes, in addition to the per-tender receipts. _Example: Receipt for an approved sale_ Returns the authorization receipt of an approved sale or authorization, generating it if it hasn't been generated yet. Put the transaction id in the route as transactionId. Sending the same request again returns the same receipt id. ```json { "receiptType": "Authorization" } ``` _Example: On-demand copy_ Generates an on-demand copy of the transaction's receipt, for a reprint. Put the transaction id in the route as transactionId. A retry of the same request returns the copy it just generated rather than a second one. ```json { "receiptType": "OnDemand" } ``` ## Responses ### 200 The existing or newly generated receipt. **Content type:** `application/json` Schema: [`TransactionReceiptDto`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/TransactionReceiptDto.md) Properties: - `id` (string(uuid)): The receipt id. - `transactionId` (string(uuid)): The transaction this receipt belongs to. - `merchantId` (string(uuid)): The merchant that owns the transaction. - `receiptType` ([ReceiptType](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ReceiptType.md)): The event in the transaction's life that this receipt records. Values: - `Authorization`: Receipt generated after a successful authorization. - `Capture`: Receipt generated after a capture/settlement. - `Refund`: Receipt generated after a full refund. - `PartialRefund`: Receipt generated after a partial refund. Multiple partial refund receipts may exist on a single transaction, each with a distinct sequence number. - `Void`: Receipt generated after a void. - `Reversal`: Receipt generated after a full reversal: the entire approved amount has been released back to the issuer. Distinguished from PartialReversal so the transaction-detail / explorer pages can show the lifecycle event clearly. - `OnDemand`: Receipt generated on-demand from the UI (legacy/fallback for pre-module transactions). - `PartialReversal`: Receipt generated after a partial reversal. Multiple partial reversal receipts may exist on a single transaction (one per reversal operation), each with a distinct sequence number. - `SplitTenderSummary`: Summary receipt for a completed split tender group: the order total, what each tender in the group authorized, and the combined authorized amount. Generated once per group, after the final tender completes, in addition to the per-tender receipts. - `sequenceNumber` (integer(int32)): The receipt's position among the transaction's receipts, starting at 1. - `generatedAtUtc` (string(date-time)): When the receipt was generated, in UTC. - `confirmationNumber` (string): The confirmation number printed on the receipt. (nullable) - `transactionType` ([TransactionType](https://devportal.signapay-sbx.winkpg.io/docs/api/models/TransactionType.md)): The transaction type. Values: - `Authorization`: Represents an authorization transaction, typically used to verify funds availability without capturing the amount. - `Sale`: Represents a sale transaction, which authorizes and captures funds in a single step. - `Return`: Represents a return transaction, used to refund money to the customer. - `Void`: Represents a void transaction, used to cancel a previously authorized transaction before it is settled. - `Force`: Represents a force transaction, typically used to manually enter a previously authorized transaction. - `Capture`: Represents a capture transaction, used to capture funds from a previously authorized transaction. - `CaptureAll`: Represents a capture all transaction, used to capture funds from multiple previously authorized transactions. - `RepeatSale`: Represents a repeat sale transaction, used to process a new sale based on a previous transaction's details. - `Adjustment`: Represents an adjustment transaction, used to modify the amount of a previous transaction. - `Activate`: Represents an activate transaction, typically used to activate a gift card or prepaid card. - `Deactivate`: Represents a deactivate transaction, typically used to deactivate a gift card or prepaid card. - `Redeem`: Represents a redeem transaction, typically used to redeem value from a gift card or loyalty program. - `Inquire`: Represents an inquire transaction, used to check the status or balance of an account or card. - `Reload`: Represents a reload transaction, typically used to add value to a gift card or prepaid card. - `VoucherClear`: Represents an offline EBT voucher clear: a terminal was offline, a paper food-stamp (SNAP) or eWIC voucher was written against a voice-obtained approval code, and the voucher is later uploaded so the benefit clears. Permitted on EBT SNAP and eWIC tenders only. - `Payout`: Represents a payout transaction, used to push funds from the merchant to an external bank account as an ACH credit. Unlike Return, which refunds a prior debit, a payout is a standalone outbound fund transfer with no originating transaction. - `statusDisplay` (string): The status printed on the receipt: Approved, Partially Approved, Pending, Not Completed or Declined. (nullable) - `isApproved` (boolean): Whether the transaction was approved when the receipt was generated. - `authorizationCode` (string): The processor's authorization code. Present only on an approved receipt. (nullable) - `declineReason` (string): Why the transaction was declined. Present only when `isApproved` is false. (nullable) - `processorMessage` (string): The processor's response message. (nullable) - `signatureRequired` (boolean): Whether the receipt asks for the cardholder's signature. - `customerEmail` (string): The customer email address captured on the transaction. (nullable) - `transactionDateUtc` (string(date-time)): When the transaction took place, in UTC. - `transactionDateLocal` (string): When the transaction took place, formatted in the merchant's time zone as printed on the receipt. (nullable) - `merchantInfo` ([ReceiptMerchantInfoDto](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ReceiptMerchantInfoDto.md)): The merchant details printed on the receipt. Fields: - `name` (string): Merchant legal name. (nullable) - `dba` (string): "Doing Business As" name. (nullable) - `logoUrl` (string): Absolute URL to the merchant logo. (nullable) - `brandColor` (string): Brand accent color (hex). (nullable) - `address` (string): Pre-formatted display address. (nullable) - `phone` (string): Support phone number. (nullable) - `email` (string): Support email. (nullable) - `footerText` (string): Custom footer text. (nullable) - `terminalId` (string): Terminal/register identifier (TID). From the POS register or lane name. (nullable) - `termsAndConditions` (string): Merchant terms and conditions of sale (e.g. "No Refunds"). Printed at the foot of the receipt. (nullable) - `cardSummary` ([ReceiptCardSummaryDto](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ReceiptCardSummaryDto.md)): The payment method printed on the receipt. A card is identified by its brand and last four digits only. Fields: - `lastFour` (string): Last four digits of the card number (e.g. "4242"). (nullable) - `cardBrand` (string): Card brand (e.g. "Visa", "Mastercard"). (nullable) - `cardholderName` (string): Cardholder name. (nullable) - `entryMode` ([EntryModes](https://devportal.signapay-sbx.winkpg.io/docs/api/models/EntryModes.md)): Card entry mode. (nullable) Values: - `Unknown`: The entry mode is unknown. - `NotApplicable`: The entry mode is not applicable for this transaction. - `Manual`: The transaction details were entered manually. - `UnencryptedCardReaderSwipe`: The card was swiped through an unencrypted card reader. - `EncryptedCardReaderSwipe`: The card was swiped through an encrypted card reader. - `Icc`: The transaction was processed using an ICC (Integrated Circuit Card) or chip card. - `Proximity`: The transaction was processed using a proximity or contactless payment method. - `Fallback`: The transaction was processed using a fallback method when the primary method failed. - `TechnicalFallback`: The transaction was processed using a fallback method when the primary method failed. - `EmptyCandidateFallback`: The transaction was processed using a fallback method when the primary method failed. - `DigitalWallet`: The transaction was processed using a digital wallet. - `avsResponseCode` (string): AVS response code. (nullable) - `avsResponseText` (string): Human-readable AVS response. (nullable) - `paymentType` (string): Payment type derived from BIN data (e.g. "Credit", "Debit"). Printed so the receipt says whether the card was a credit or a debit card, which processor receipt rules require. (nullable) - `tenderType` ([CardTenderType](https://devportal.signapay-sbx.winkpg.io/docs/api/models/CardTenderType.md)): Card-rail tender used for the transaction. Surfaces this on receipts so EBT SNAP / EBT Cash / WIC transactions render program-appropriate language even when the BIN-derived `paymentType` would label them generically (e.g. "Debit"). Null when the transaction recorded no tender; the receipt then uses the generic credit/debit layout. (nullable) Values: - `CreditDebit`: Standard credit/debit card. The current card-rail behaviour. isDebitRouting modulates whether the request prefers debit-network routing within this rail. - `EbtSnap`: EBT SNAP (food benefits). Routes through the EBT SNAP processor lane and requires PIN + card-present per program rules. - `EbtCash`: EBT Cash (cash benefits). Distinct rail from SNAP; supports cashback where SNAP does not. PIN + card-present required. - `Ewic`: eWIC (Women, Infants, and Children). Distinct rail from EBT, with item-level eligibility / voucher-select flow handled in the eWIC follow-up epic. - `ebtBalanceAvailable` (number(double)): EBT balance available after the transaction, when the processor returns it on the authorization response. `null` when not applicable (credit/debit) or not provided by the processor. receipts render this value on a dedicated "EBT Balance Available" line for EBT SNAP / EBT Cash transactions. (nullable) - `tenderLabel` (string): Human-readable label for the tender (e.g. "Credit / Debit", "EBT SNAP", "EBT Cash", "WIC"). Pre-formatted by the receipt assembler so renderers don't need to localize the enum themselves. (nullable) - `amountSummary` ([ReceiptAmountSummaryDto](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ReceiptAmountSummaryDto.md)): The amounts printed on the receipt. Fields: - `subtotal` (number(double)): Subtotal (base amount before tax and tip), in the transaction currency. (nullable) - `tax` (number(double)): Tax amount, in the transaction currency. (nullable) - `tip` (number(double)): Tip/gratuity amount, in the transaction currency. (nullable) - `shipping` (number(double)): Shipping amount, in the transaction currency. Null / zero when no shipping amount was collected, in which case no shipping line is rendered. (nullable) - `total` (number(double)): Total transaction amount, in the transaction currency. (nullable) - `approvedAmount` (number(double)): Approved amount, in the transaction currency (may differ from total for partial approvals). (nullable) - `isPartialApproval` (boolean): Whether the approval was partial. - `requestedAmount` (number(double)): The amount requested from the card issuer, in the transaction currency. Present on a partial approval receipt, where it is printed beside `approvedAmount`, and on a split tender summary, where it is the order total. Null on every other receipt. (nullable) - `remainingBalanceAfterApproval` (number(double)): What a partial approval left unpaid on this card: `requestedAmount` minus `approvedAmount`, never negative. On a split tender summary, what the group as a whole left unpaid. In the transaction currency. Null whenever `requestedAmount` is null. (nullable) - `currencyCode` (string): ISO 4217 currency code (e.g. "USD"). (nullable) - `cashBack` (number(double)): Cash back (debit) or cash over (Discover credit) amount, in the transaction currency. Printed on Discover credit and debit receipts, where the processor's receipt rules require it. (nullable) - `transactionFee` (number(double)): Transaction fee assessed (e.g. PIN debit fees), in the transaction currency. Included when provided by the processor. (nullable) - `availableBalance` (number(double)): Available balance remaining after the transaction, in the transaction currency. Included when provided by the processor (credit, debit, EBT, prepaid). (nullable) - `convenienceFee` (number(double)): Convenience fee assessed on the transaction, in the transaction currency. Null / zero when no convenience fee applies, in which case no fee line is rendered. (nullable) - `convenienceFeeBilledSeparately` (boolean): True when the convenience fee was submitted as its own separately-authorized charge rather than being included in this transaction's `total`. The fee line is then rendered with a "billed as a separate charge" qualifier so the total still reconciles. - `surcharge` (number(double)): Surcharge amount assessed on the transaction, in the transaction currency. Present only when the gateway computed and applied a surcharge; null otherwise (a non-surcharged transaction shows no surcharge line). (nullable) - `surchargeRate` (number(double)): The surcharge rate applied to produce `surcharge`, as a decimal fraction (e.g. 0.03 for 3%). (nullable) - `surchargeReversed` (number(double)): Surcharge amount reversed back to the cardholder on a refund / reversal receipt, in the transaction currency. Null / zero on non-refund receipts. (nullable) - `cashPrice` (number(double)): For a merchant that posts a cash price and a card price, the cash price of this payment, in the transaction currency: its base amount. Present, with `cardPrice`, only when the payment was charged one of the two posted prices; null otherwise, and the receipt then prints its ordinary subtotal. (nullable) - `cardPrice` (number(double)): For a merchant that posts a cash price and a card price, the card price of this payment, in the transaction currency: the cash price plus the merchant's card rate. On a card payment it is the price charged; on a cash or bank payment it is the price the payer did not pay. Null when the payment was not dual priced. (nullable) - `cashDiscountAmount` (number(double)): The discount a payment charged the cash price received, in the transaction currency: `cardPrice` minus `cashPrice`. Present only on a cash payment, or a bank payment the merchant treats as cash; null on a card payment and when the payment was not dual priced. (nullable) - `cashDiscountForBankPayment` (boolean): True when `cashDiscountAmount` was received by a bank payment rather than cash. False whenever no cash discount applies. - `cardPriceReversed` (number(double)): The share of the card price returned to the payer on a void, reversal or refund of a payment charged the card price, in the transaction currency. Not printed as a row of its own: the refunded total already includes it. Null when nothing of a card price was returned. (nullable) - `customFields` (array<[ReceiptCustomFieldDto](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ReceiptCustomFieldDto.md)>): The transaction custom fields the merchant chose to show on receipts. (nullable) Fields of each item: - `name` (string): Custom field display name. (nullable) - `value` (string): Custom field value. (nullable) - `values` (array): The list of values for a multi-value custom field, or `null` for a single-value field. A renderer shows one item per line; `value` is `null` when this is set unless the field was captured through its single value, in which case both are present. (nullable) - `originalSaleDateUtc` (string(date-time)): On a refund receipt, when the original sale took place, in UTC. (nullable) - `refundReason` (string): On a refund receipt, the reason given for the refund. (nullable) - `emailSent` (boolean): Whether the receipt has been emailed. - `linkedChargeRole` ([LinkedChargeRole](https://devportal.signapay-sbx.winkpg.io/docs/api/models/LinkedChargeRole.md)): Which half of a linked pair of charges this receipt covers, or null when the transaction is not part of one. (nullable) Values: - `PrimaryCharge`: The primary payment. A separate fee charge was authorized alongside it, so this transaction's own amount is not the whole of what the cardholder was billed. - `FeeCharge`: The separately-authorized fee charge. The payment it was assessed against is a different transaction with its own authorization and approval code. - `linkedChargeTransactionId` (string): The id of the other transaction in the linked pair, or null when there is none. (nullable) - `linkedChargeKind` ([LinkedChargeKind](https://devportal.signapay-sbx.winkpg.io/docs/api/models/LinkedChargeKind.md)): Why the other charge in the pair exists. Present on the fee charge's own receipt only. (nullable) Values: - `ConvenienceFee`: A separate charge submitted to carry a convenience fee that a card-brand program requires to settle as its own authorization (its own approval code), linked to the primary payment it was assessed against. - `splitTenderContext` ([ReceiptSplitTenderContextDto](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ReceiptSplitTenderContextDto.md)): The split tender group this receipt belongs to, or null when the transaction is not part of a split tender. Fields: - `groupId` (string(uuid)): Identifier shared by every tender in the group. (nullable) - `tenderSequence` (integer(int32)): 1-based position of this receipt's transaction within the group. Null on a split tender summary, which covers the whole group. (nullable) - `totalTendersInGroup` (integer(int32)): Number of tenders in the group, voided ones included. Null when the group size was not known when the receipt was generated, which is the case on a per-tender receipt. (nullable) - `groupTotalAuthorized` (number(double)): Combined amount authorized across the tenders in the group that were not voided or reversed, in the transaction currency. Null when the whole group was not known when the receipt was generated. (nullable) - `returnedAmount` (number(double)): What the bank took back from the group after it completed: the sum of the lines marked `isReturned`, in the transaction currency. Null on every receipt that shows no return, including the summary issued when the group completed. (nullable) - `tenders` (array<[ReceiptSplitTenderLineDto](https://devportal.signapay-sbx.winkpg.io/docs/api/models/ReceiptSplitTenderLineDto.md)>): One line per tender, ordered by sequence. Populated on a split tender summary; empty otherwise. (nullable) ### 429 The request was refused because a rate limit was exceeded, or because something a later retry can clear stopped it. A rate limit refusal carries an `application/problem+json` body: wait at least the interval `Retry-After` names before retrying, then back off. Limits are tuned per deployment, so read the allowance from the response headers rather than assuming a fixed ceiling. Any other refusal carries the standard error envelope as `application/json`, and its `error.code` names the cause. **Content type:** `application/problem+json` Schema: [`RateLimitProblemDetails`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RateLimitProblemDetails.md) Properties: - `type` (string) required: The problem type identifier. Always the same value: the failure is the status code itself, so there is no sub-type for a caller to branch on. (nullable) - `title` (string) required: A short, human-readable summary of the problem type. (nullable) - `status` (integer(int32)) required: The HTTP status code, repeated in the body as the problem-details format defines. - `detail` (string) required: A human-readable explanation of this occurrence of the problem. (nullable) - `retryAfterSeconds` (integer(int32)) required: How long to wait before retrying, in whole seconds, carrying the same figure as the `Retry-After` header. Always at least one: a value of zero would invite an immediate retry that is certain to be rejected again. **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) ### 400 The receipt type is missing, unknown, or `SplitTenderSummary`. **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) _Example: Request failed validation_ One or more fields were rejected before any rule ran. error.code is null on the envelope and the causes are in validationErrors, one entry per failure. An entry carries code when the validator declared a publishable one, and memberPaths when the full path says more than members does (an element inside a collection, for example). Both keys are omitted when they would add nothing. ```json { "error": { "code": null, "message": "Your request is not valid!", "details": "The following errors were detected during validation.", "data": { "correlationId": "0123456789abcdef0123456789abcdef" }, "validationErrors": [ { "message": "'Amount' must be greater than 0.", "members": [ "amount" ] }, { "message": "The card has expired.", "members": [ "expirationDate" ], "code": "CardData:CardExpired" }, { "message": "'Value' must not be empty.", "members": [ "value" ], "memberPaths": [ "customFields[2].value" ] } ] } } ``` ### 401 Unauthorized. The request carried no API key or signed-in session, or the key it carried is invalid, revoked or expired. **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) ### 403 Forbidden. The API key lacks the scope this operation needs, the signed-in user lacks the permission, or a business rule refused the request. The error code in the body names the reason. **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) ### 404 No transaction with that id is visible to this caller for that merchant. **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) _Example: Resource not found_ The id in the path names no record the caller can see. Most resources answer with a null error.code and a message naming the resource type and the id; a resource that publishes a not-found code in the catalog above carries it in error.code instead, so check for one before matching on the message. ```json { "error": { "code": null, "message": "There is no entity Transaction with id = 7d1f3a52-0c4e-4b8a-9e21-5a6b7c8d9e00!", "details": null, "data": { "correlationId": "0123456789abcdef0123456789abcdef" }, "validationErrors": null } } ``` ### 500 Internal server error. The platform failed unexpectedly while handling the request. If it keeps failing, contact support and quote the correlation id, which the response carries in the `X-Correlation-Id` header and as `error.data.correlationId`. **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) ### 501 Not implemented. The operation is declared but has no implementation on this deployment, so no request to it can succeed. Retrying does not help. **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) ### default The request failed. The body carries the standard error envelope: a machine-readable `error.code`, a human-readable `error.message`, and `error.validationErrors` when the failure was a validation rejection. The [error reference](https://devportal.signapay-sbx.winkpg.io/docs/errors.md) lists the values `error.code` can take. **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) _Example: Business rule refused the request_ The request was understood and rejected by a platform rule. This is the shape that carries a code from the catalog above, so branch on error.code rather than on the message text. The HTTP status is the one listed against the code. ```json { "error": { "code": "Transactions:OperationNotAllowed", "message": "The operation 'Void' is not allowed on a Sale transaction with result 'Approved' and settlement state 'Settled'.", "details": null, "data": { "correlationId": "0123456789abcdef0123456789abcdef" }, "validationErrors": null } } ``` ### Errors These statuses answer with the error envelope outlined below. - `400`: The receipt type is missing, unknown, or `SplitTenderSummary`. - `401`: Unauthorized. The request carried no API key or signed-in session, or the key it carried is invalid, revoked or expired. - `403`: Forbidden. The API key lacks the scope this operation needs, the signed-in user lacks the permission, or a business rule refused the request. The error code in the body names the reason. - `404`: No transaction with that id is visible to this caller for that merchant. - `500`: Internal server error. The platform failed unexpectedly while handling the request. If it keeps failing, contact support and quote the correlation id, which the response carries in the `X-Correlation-Id` header and as `error.data.correlationId`. - `501`: Not implemented. The operation is declared but has no implementation on this deployment, so no request to it can succeed. Retrying does not help. - `default`: The request failed. The body carries the standard error envelope: a machine-readable `error.code`, a human-readable `error.message`, and `error.validationErrors` when the failure was a validation rejection. The [error reference](https://devportal.signapay-sbx.winkpg.io/docs/errors.md) lists the values `error.code` can take. **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) Fields: - `code` (string): (nullable) - `message` (string): (nullable) - `details` (string): (nullable) - `data` (object): (nullable) - `validationErrors` (array<[RemoteServiceValidationErrorInfo](https://devportal.signapay-sbx.winkpg.io/docs/api/models/RemoteServiceValidationErrorInfo.md)>): (nullable) _Example: Request failed validation_ One or more fields were rejected before any rule ran. error.code is null on the envelope and the causes are in validationErrors, one entry per failure. An entry carries code when the validator declared a publishable one, and memberPaths when the full path says more than members does (an element inside a collection, for example). Both keys are omitted when they would add nothing. ```json { "error": { "code": null, "message": "Your request is not valid!", "details": "The following errors were detected during validation.", "data": { "correlationId": "0123456789abcdef0123456789abcdef" }, "validationErrors": [ { "message": "'Amount' must be greater than 0.", "members": [ "amount" ] }, { "message": "The card has expired.", "members": [ "expirationDate" ], "code": "CardData:CardExpired" }, { "message": "'Value' must not be empty.", "members": [ "value" ], "memberPaths": [ "customFields[2].value" ] } ] } } ``` ## Authentication - `ApiKey` ## Example request Every block below sends the same request. Replace {{BASE_URL}} with the address of the API you are calling and {{API_KEY}} with your own key. The request body is a GenerateTransactionReceiptInput. See the Request body section below for its fields. These blocks send the Receipt for an approved sale example. The other examples follow under Other request examples. Returns the authorization receipt of an approved sale or authorization, generating it if it hasn't been generated yet. Put the transaction id in the route as transactionId. Sending the same request again returns the same receipt id. ### cURL ```bash curl -X POST "{{BASE_URL}}/api/transactions/by-merchant/{merchantId}/{transactionId}/receipts" \ -H "api-key: {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "receiptType": "Authorization" }' ``` ### PowerShell ```powershell $headers = @{ 'api-key' = '{{API_KEY}}' } $body = @' { "receiptType": "Authorization" } '@ $response = Invoke-RestMethod -Method POST -Uri '{{BASE_URL}}/api/transactions/by-merchant/{merchantId}/{transactionId}/receipts' ` -Headers $headers -ContentType 'application/json' -Body $body ``` ### TypeScript (SDK) ```bash npm install @winkpg/winkpg-api ``` ```typescript import { Configuration, TransactionsApi } from '@winkpg/winkpg-api'; const api = new TransactionsApi(new Configuration({ basePath: '{{BASE_URL}}', apiKey: '{{API_KEY}}', })); const { data } = await api.transactionReceiptsGenerate("3fa85f64-5717-4562-b3fc-2c963f66afa6", "3fa85f64-5717-4562-b3fc-2c963f66afa6", { "receiptType": "Authorization" }); ``` ### TypeScript (raw HTTP) ```typescript const response = await fetch('{{BASE_URL}}/api/transactions/by-merchant/{merchantId}/{transactionId}/receipts', { method: 'POST', headers: { "api-key": "{{API_KEY}}", "Content-Type": "application/json", }, body: JSON.stringify({ "receiptType": "Authorization" }), }); const data = await response.json(); ``` ### C# (SDK) ```bash dotnet add package WinkPg.Api.Client ``` ```csharp using WinkPg.Api.Client.Api; using WinkPg.Api.Client.Client; using System.Text.Json; var config = new Configuration { BasePath = "{{BASE_URL}}" }; config.AddApiKey("api-key", "{{API_KEY}}"); var api = new TransactionsApi(config); var body = JsonSerializer.Deserialize(""" { "receiptType": "Authorization" } """); var result = await api.TransactionReceiptsGenerateAsync(Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6"), Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6"), body); ``` ### C# (raw HTTP) ```csharp using System.Text; using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") }; var request = new HttpRequestMessage(new HttpMethod("POST"), "/api/transactions/by-merchant/{merchantId}/{transactionId}/receipts"); request.Headers.Add("api-key", "{{API_KEY}}"); request.Content = new StringContent(""" { "receiptType": "Authorization" } """, Encoding.UTF8, "application/json"); var response = await http.SendAsync(request); response.EnsureSuccessStatusCode(); var json = await response.Content.ReadAsStringAsync(); ``` ### Python (SDK) ```bash pip install winkpg-api ``` ```python import winkpg_api configuration = winkpg_api.Configuration(host="{{BASE_URL}}") configuration.api_key["ApiKey"] = "{{API_KEY}}" with winkpg_api.ApiClient(configuration) as client: api = winkpg_api.TransactionsApi(client) body = winkpg_api.GenerateTransactionReceiptInput.from_dict({ "receiptType": "Authorization" }) result = api.transaction_receipts_generate("3fa85f64-5717-4562-b3fc-2c963f66afa6", "3fa85f64-5717-4562-b3fc-2c963f66afa6", body) ``` ### Python (raw HTTP) ```bash pip install requests ``` ```python import requests headers = { "api-key": "{{API_KEY}}", "Content-Type": "application/json", } body = { "receiptType": "Authorization" } response = requests.request( "POST", "{{BASE_URL}}/api/transactions/by-merchant/{merchantId}/{transactionId}/receipts", headers=headers, json=body, ) response.raise_for_status() data = response.json() ``` ## Other request examples Each example below is one request, shown in every language with the same placeholders. ### On-demand copy Generates an on-demand copy of the transaction's receipt, for a reprint. Put the transaction id in the route as transactionId. A retry of the same request returns the copy it just generated rather than a second one. #### cURL ```bash curl -X POST "{{BASE_URL}}/api/transactions/by-merchant/{merchantId}/{transactionId}/receipts" \ -H "api-key: {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "receiptType": "OnDemand" }' ``` #### PowerShell ```powershell $headers = @{ 'api-key' = '{{API_KEY}}' } $body = @' { "receiptType": "OnDemand" } '@ $response = Invoke-RestMethod -Method POST -Uri '{{BASE_URL}}/api/transactions/by-merchant/{merchantId}/{transactionId}/receipts' ` -Headers $headers -ContentType 'application/json' -Body $body ``` #### TypeScript (SDK) ```bash npm install @winkpg/winkpg-api ``` ```typescript import { Configuration, TransactionsApi } from '@winkpg/winkpg-api'; const api = new TransactionsApi(new Configuration({ basePath: '{{BASE_URL}}', apiKey: '{{API_KEY}}', })); const { data } = await api.transactionReceiptsGenerate("3fa85f64-5717-4562-b3fc-2c963f66afa6", "3fa85f64-5717-4562-b3fc-2c963f66afa6", { "receiptType": "OnDemand" }); ``` #### TypeScript (raw HTTP) ```typescript const response = await fetch('{{BASE_URL}}/api/transactions/by-merchant/{merchantId}/{transactionId}/receipts', { method: 'POST', headers: { "api-key": "{{API_KEY}}", "Content-Type": "application/json", }, body: JSON.stringify({ "receiptType": "OnDemand" }), }); const data = await response.json(); ``` #### C# (SDK) ```bash dotnet add package WinkPg.Api.Client ``` ```csharp using WinkPg.Api.Client.Api; using WinkPg.Api.Client.Client; using System.Text.Json; var config = new Configuration { BasePath = "{{BASE_URL}}" }; config.AddApiKey("api-key", "{{API_KEY}}"); var api = new TransactionsApi(config); var body = JsonSerializer.Deserialize(""" { "receiptType": "OnDemand" } """); var result = await api.TransactionReceiptsGenerateAsync(Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6"), Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6"), body); ``` #### C# (raw HTTP) ```csharp using System.Text; using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") }; var request = new HttpRequestMessage(new HttpMethod("POST"), "/api/transactions/by-merchant/{merchantId}/{transactionId}/receipts"); request.Headers.Add("api-key", "{{API_KEY}}"); request.Content = new StringContent(""" { "receiptType": "OnDemand" } """, Encoding.UTF8, "application/json"); var response = await http.SendAsync(request); response.EnsureSuccessStatusCode(); var json = await response.Content.ReadAsStringAsync(); ``` #### Python (SDK) ```bash pip install winkpg-api ``` ```python import winkpg_api configuration = winkpg_api.Configuration(host="{{BASE_URL}}") configuration.api_key["ApiKey"] = "{{API_KEY}}" with winkpg_api.ApiClient(configuration) as client: api = winkpg_api.TransactionsApi(client) body = winkpg_api.GenerateTransactionReceiptInput.from_dict({ "receiptType": "OnDemand" }) result = api.transaction_receipts_generate("3fa85f64-5717-4562-b3fc-2c963f66afa6", "3fa85f64-5717-4562-b3fc-2c963f66afa6", body) ``` #### Python (raw HTTP) ```bash pip install requests ``` ```python import requests headers = { "api-key": "{{API_KEY}}", "Content-Type": "application/json", } body = { "receiptType": "OnDemand" } response = requests.request( "POST", "{{BASE_URL}}/api/transactions/by-merchant/{merchantId}/{transactionId}/receipts", headers=headers, json=body, ) response.raise_for_status() data = response.json() ``` ## See also - [All documentation](https://devportal.signapay-sbx.winkpg.io/llms.txt): the machine-readable index of every public page on this site.