Creates a transaction from a consumed hosted payment page session.

POST /api/transactions/from-hpp-session deprecated

No permission required.

The session stands in for the caller's credentials, so this route takes no permission of its own and derives the merchant from the session rather than from the request. Anyone holding a valid session and transaction id pair can call it; that is the contract, and the session is the credential. When the pair does not check out, the request is refused with the `Transactions:HppSessionLinkVerificationFailed` business code, which reports nothing about why.

Try this in the console

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 TransactionCreateDto. See the Request body section below for its fields.

cURL PowerShell TypeScript C# Python

cURL

curl -X POST "{{BASE_URL}}/api/transactions/from-hpp-session" \
  -H "api-key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
  "merchantId": "00000000-0000-0000-0000-000000000001",
  "transactionType": "Authorization",
  "cardData": {
    "cardNumber": "4111111111111111",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "cvv": 123,
    "nameOnCard": "John Doe",
    "entryMode": "Manual",
    "cvPresence": "Submitted"
  },
  "duplicateCheck": true,
  "invoiceData": {
    "amounts": {
      "base": 1,
      "total": 1
    }
  }
}'

PowerShell

$headers = @{
    'api-key' = '{{API_KEY}}'
}

$body = @'
{
  "merchantId": "00000000-0000-0000-0000-000000000001",
  "transactionType": "Authorization",
  "cardData": {
    "cardNumber": "4111111111111111",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "cvv": 123,
    "nameOnCard": "John Doe",
    "entryMode": "Manual",
    "cvPresence": "Submitted"
  },
  "duplicateCheck": true,
  "invoiceData": {
    "amounts": {
      "base": 1,
      "total": 1
    }
  }
}
'@

$response = Invoke-RestMethod -Method POST -Uri '{{BASE_URL}}/api/transactions/from-hpp-session' `
    -Headers $headers -ContentType 'application/json' -Body $body

npm install @winkpg/winkpg-api

TypeScript (SDK)

import { Configuration, TransactionsApi } from '@winkpg/winkpg-api';

const api = new TransactionsApi(new Configuration({
  basePath: '{{BASE_URL}}',
  apiKey: '{{API_KEY}}',
}));

const { data } = await api.transactionsCreateFromHppSession({
  "merchantId": "00000000-0000-0000-0000-000000000001",
  "transactionType": "Authorization",
  "cardData": {
    "cardNumber": "4111111111111111",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "cvv": 123,
    "nameOnCard": "John Doe",
    "entryMode": "Manual",
    "cvPresence": "Submitted"
  },
  "duplicateCheck": true,
  "invoiceData": {
    "amounts": {
      "base": 1,
      "total": 1
    }
  }
});

TypeScript (raw HTTP)

const response = await fetch('{{BASE_URL}}/api/transactions/from-hpp-session', {
  method: 'POST',
  headers: {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "merchantId": "00000000-0000-0000-0000-000000000001",
    "transactionType": "Authorization",
    "cardData": {
      "cardNumber": "4111111111111111",
      "expirationMonth": 12,
      "expirationYear": 2030,
      "cvv": 123,
      "nameOnCard": "John Doe",
      "entryMode": "Manual",
      "cvPresence": "Submitted"
    },
    "duplicateCheck": true,
    "invoiceData": {
      "amounts": {
        "base": 1,
        "total": 1
      }
    }
  }),
});

const data = await response.json();

dotnet add package WinkPg.Api.Client

C# (SDK)

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<TransactionCreateDto>("""
    {
      "merchantId": "00000000-0000-0000-0000-000000000001",
      "transactionType": "Authorization",
      "cardData": {
        "cardNumber": "4111111111111111",
        "expirationMonth": 12,
        "expirationYear": 2030,
        "cvv": 123,
        "nameOnCard": "John Doe",
        "entryMode": "Manual",
        "cvPresence": "Submitted"
      },
      "duplicateCheck": true,
      "invoiceData": {
        "amounts": {
          "base": 1,
          "total": 1
        }
      }
    }
    """);

var result = await api.TransactionsCreateFromHppSessionAsync(body);

C# (raw HTTP)

using System.Text;

using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") };

var request = new HttpRequestMessage(new HttpMethod("POST"), "/api/transactions/from-hpp-session");
request.Headers.Add("api-key", "{{API_KEY}}");

request.Content = new StringContent("""
    {
      "merchantId": "00000000-0000-0000-0000-000000000001",
      "transactionType": "Authorization",
      "cardData": {
        "cardNumber": "4111111111111111",
        "expirationMonth": 12,
        "expirationYear": 2030,
        "cvv": 123,
        "nameOnCard": "John Doe",
        "entryMode": "Manual",
        "cvPresence": "Submitted"
      },
      "duplicateCheck": true,
      "invoiceData": {
        "amounts": {
          "base": 1,
          "total": 1
        }
      }
    }
    """, Encoding.UTF8, "application/json");

var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync();

pip install winkpg-api

Python (SDK)

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.TransactionCreateDto.from_dict({
      "merchantId": "00000000-0000-0000-0000-000000000001",
      "transactionType": "Authorization",
      "cardData": {
        "cardNumber": "4111111111111111",
        "expirationMonth": 12,
        "expirationYear": 2030,
        "cvv": 123,
        "nameOnCard": "John Doe",
        "entryMode": "Manual",
        "cvPresence": "Submitted"
      },
      "duplicateCheck": True,
      "invoiceData": {
        "amounts": {
          "base": 1,
          "total": 1
        }
      }
    })
    result = api.transactions_create_from_hpp_session(body)

pip install requests

Python (raw HTTP)

import requests

headers = {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
}

body = {
  "merchantId": "00000000-0000-0000-0000-000000000001",
  "transactionType": "Authorization",
  "cardData": {
    "cardNumber": "4111111111111111",
    "expirationMonth": 12,
    "expirationYear": 2030,
    "cvv": 123,
    "nameOnCard": "John Doe",
    "entryMode": "Manual",
    "cvPresence": "Submitted"
  },
  "duplicateCheck": True,
  "invoiceData": {
    "amounts": {
      "base": 1,
      "total": 1
    }
  }
}

response = requests.request(
    "POST",
    "{{BASE_URL}}/api/transactions/from-hpp-session",
    headers=headers,
    json=body,
)
response.raise_for_status()
data = response.json()

Parameters

Name	In	Type	Description
`hppSessionId` required	query	string (uuid)	The hosted payment page session the cardholder consumed when submitting. It must already be linked to the transaction named in `input`.
`suppressNulls` required	query	boolean	If true, omit properties with null values.

Request body

application/json , required

Field	Type	Description
`currentStage` required	all of TransactionStage	Gets or sets the current stage of the transaction within the create or update workflow.
`history` required	array of TransactionHistoryItem	Gets or sets the transaction history entries associated with the transaction. nullable
`appliedPatches` required	array of TransactionPatchSnapshot	Gets or sets the collection of patch snapshots that have been applied to the transaction. nullable
`merchantId` required	string (uuid)	The unique identifier of the merchant associated with the transaction.
`transactionType` required	all of TransactionType	The type of transaction being performed. Conditional: When RequestedSplitTenderTotal is not null. Must equal Sale. Conditional: Conditional (see validator source).
`description` required	string	Optional free-text description of what this payment is for, at most 100 characters. nullablemax length 100
`merchantReference` required	string	Optional merchant-supplied reference for reconciliation, at most 25 characters, letters and digits only. nullablemax length 25pattern ^[A-Za-z0-9]*$
`tender` required	all of TenderKind	Optionally declares that this transaction is taken in cash. The only accepted value is `Cash`. Omit the field for every card, check, and token transaction. nullable
`cardData` required	all of CardData	Card data associated with the transaction. Conditional: When CardData is not null. Required: Conditional (see validator source).
`checkData` required	all of CheckData	Check data associated with the transaction. Conditional: When CheckData is not null. Conditional: Conditional (see validator source). Conditional: When TransactionType == VoucherClear. Required: When TransactionType == Payout.
`cashData` required	all of CashPaymentDetails	Cash sale details: the cash handed over, the change returned, and when the cash was taken.
`tokenData` required	all of TokenData	Tokenized payment details, used to charge a stored credential instead of raw card data. Conditional: When TokenData is not null.
`deviceData` required	all of DeviceData	Device data for the transaction. Conditional: When DeviceData is not null.
`fsa` required	all of Fsa	FSA (Flexible Spending Account) data for the transaction.
`lodging` required	all of LodgingData	Lodging detail for a stay-related transaction, for merchants transacting under a lodging industry. Conditional: When Lodging is not null.
`softDescriptor` required	all of SoftDescriptor	Soft descriptor information for the transaction.
`duplicateCheck` required	boolean	Indicates whether to perform a duplicate check for the transaction. Omit the field to let the merchant's screening configuration decide, which is what happens today. Send false to waive the check, which the merchant must have permitted. Sending true never turns screening on for a merchant who has not configured it. nullable
`register` required	all of TransactionRegister	Register information for the transaction.
`invoiceData` required	all of Invoice	Invoice data associated with the transaction, carrying the customer and the amounts. Required: Conditional (see validator source). Required: When TransactionType == Capture.
`originalTransaction` required	all of OriginalTransaction	Data about the original transaction, if applicable.
`customFields` required	array of TrxCustomField	Custom fields for the transaction. Conditional: When CustomFields is not null. nullable
`signatureData` required	all of SignatureData	Signature data for the transaction.
`level2Data` required	all of Level2Data	Level 2 data for the transaction (e.g., tax, purchase order).
`level3Data` required	all of Level3Data	Level 3 data for the transaction (e.g., line item details).
`ebt` required	all of EbtData	EBT voucher data for the transaction (offline SNAP / Cash voucher-clear flow).
`useInterchangeDefaults` required	boolean	Indicates whether to use interchange defaults for the transaction. nullable
`skipOrderDataDefaults` required	boolean	When true, the server does not apply the merchant's configured Level 2/3 defaults to the transaction. Set by the Virtual Terminal when the operator chose "Enter Manually" in the BIN-driven prompt. API submissions usually leave this null. nullable
`captureType` required	all of CaptureTypes	The capture type for the transaction.
`responseData` required	all of TransactionResponseData	Response data for the transaction.
`settleData` required	all of TransactionSettleData	Settlement data for the transaction.
`processorKey` required	string	The processor type key (e.g. "tsys", "fiserv") that processed this transaction. Display-only: set during authorization and not modifiable via create/update. nullable
`sourceData` required	all of TransactionSourceData	Gets or sets the source data associated with the transaction. Conditional: When SourceData is not null.
`tags` required	array of EntityTag	Tags associated with the transaction. nullable
`notes` required	array of EntityNote	Notes associated with the transaction. nullable
`merchantTransactionId` required	integer (int64)	The unique identifier of the merchant transaction. nullable
`idempotencyKey` required	string	Your own identifier for this create request, used to make a retry safe. Send the same value again and the gateway returns the transaction the first request produced instead of charging a second time. This is the recommended pattern for reconciling a create whose response you never received. nullable
`receiptIds` required	array of string	List of receipt IDs generated for this transaction. Used for point-read access to receipts. Stored as strings: see `receiptIds` remarks for rationale. Read-only: set by the server; ignored on the AutoMapper write maps. nullableread only
`decisionNotes` required	array of TransactionDecisionNote	System-emitted decision explanations recorded against this transaction, surfaced read-only on the transaction-detail view. Like `receiptIds`, this is server state: it is populated on load for display but ignored on the create/update write maps, so a client can never persist decision notes. nullable
`initiationType` required	all of InitiationType	Identifies whether this transaction was initiated by the cardholder (CIT) or the merchant (MIT). nullable
`mitReason` required	all of MITReasonCode	For merchant-initiated transactions, the reason code justifying the MIT. Null for CITs. nullable
`storedCredentialConsentId` required	string (uuid)	Reference to the `StoredCredentialConsent` that authorizes this MIT. Null for CITs. Optional, and best omitted: when it is absent the server resolves the consent from the stored credential itself (resolved from the token plus `InvoiceData.CustomerId`) and selects the most recently captured one that permits the declared MIT reason. Send a value only to pin a specific consent when the credential carries several, for example after a re-enrollment, and only when the value is a consent identifier this platform issued for that same credential (from a capture response, a consent lookup, or a webhook). A supplied value is validated strictly and is rejected if it belongs to a different credential, has been revoked, or does not permit the declared reason. Note that a credential whose consent lineage predates this platform's consent tracking has no consent record at all: an identifier minted by a prior system is never valid here, so such a charge is rejected with `stored_credential_consent_required` whether or not this field is sent. Remediate by having the merchant attest the credential, which mints a new platform consent; the charge then succeeds with the field omitted, and the newly issued identifier is accepted when sent. nullable
`schemeTransactionId` required	string	The card network's trace ID for this transaction chain. Captured from the processor response on the initial CIT and referenced on subsequent MITs. Read-only: set by the server; ignored on the AutoMapper write maps. nullableread only
`cardholderPresence` required	all of CardholderPresence	How present the cardholder is at the point of sale, separate from the physical entry mode. Drives network-level presence indicators (e.g. TSYS `POSEnvironmentIndicator`) at auth time. `null` means "let the classifier infer from EntryMode + Source". Conditional: When CardholderPresence is not null. nullable
`specialCondition` required	all of SpecialCondition	Visa/MC special-condition tag (quasi-cash, quasi-MOTO). `null` defaults to `None`. Drives TSYS `SpecialConditionIndicator` + `CardholderId` when set to `QuasiCash`. Conditional: When SpecialCondition is not null. nullable
`processorCertificationOverrides` required	all of ProcessorCertificationOverrides	Per-processor certification override knobs. Production traffic must leave this `null`; `ICertificationOverridesGate` rejects requests where it is set unless the merchant is flagged as a test merchant AND the active processor profile has `AcceptCertificationOverrides` enabled.
`cumulativeRefundedAmount` required	number (double)	Running total of refund amounts applied to this transaction. Read-only: computed from refund operations. nullableread only
`cumulativeReversedAmount` required	number (double)	Running total of reversal amounts applied to this transaction. Read-only: computed from reversal operations. nullableread only
`authorizedAmount` required	number (double)	The immutable amount the issuer authorised at the close of the Authorization stage. Read-only: set once at `CloseAuthorization`. UI uses this rather than `ResponseData.Amounts.Approved` for remaining-balance calculations because reversal contributors overwrite `/ResponseData` with the processor's reversal-response payload. nullableread only
`saveCardRequested` required	boolean	Operator (VT) or cardholder (HPP) opt-in to save the card for future merchant-initiated use. Honored only from the Virtual Terminal and the Hosted Payment Page, which capture the required cardholder consent; a transaction create API request that sets it to true is rejected with a validation error. Auth-time-only: it cannot be set on updates or on subsequent operations. nullable
`isAccountVerification` required	boolean	When `true`, this transaction is a zero-dollar account verification rather than a charge: the gateway authorizes for $0 to confirm card validity (with AVS/CVV) and immediately voids the authorization. Used by the Hosted Payment Page "save card only: don't charge me" flow to vault a card without charging it. Mutually exclusive with a non-zero amount. Auth-time-only: the AutoMapper Update and recurring-billing maps both ignore it so it cannot be set on subsequent operations. `null` (the default) is an ordinary chargeable transaction. nullable
`convenienceFeeDisclosureAcknowledgedAt` required	string (date-time)	UTC timestamp of the moment the payer accepted the disclosed convenience fee (the confirm-click, NOT the submit). This is the caller's attestation that the fee was disclosed and agreed to, and it is <b>required</b> on any request charging a non-zero `invoiceData.amounts.convenience` on a card tender, alongside `convenienceFeeDisclosureChannel`. The Virtual Terminal stamps it from its confirm modal (the CSR attesting as the cardholder's proxy) and the Hosted Payment Page from the cardholder's own acceptance; a direct API integration owns its own disclosure UX and supplies the same attestation. It may not sit more than a few minutes ahead of the gateway's clock: a disclosure cannot have been accepted after the request that reports it. Auth-time-only: the AutoMapper Update and recurring-billing maps both ignore it, so it cannot be set on subsequent operations. `null` when no fee was charged. An ACH / e-check debit is out of scope; a convenience fee on an EBT / eWIC tender is prohibited outright and rejected before this field is examined. nullable
`convenienceFeeDisclosureChannel` required	string	The surface on which the convenience-fee disclosure was shown and accepted. One of `"VirtualTerminal"`, `"HostedPaymentPage"`, or `"Api"` (a direct integration's own checkout); matched case-insensitively, and any other value is rejected. Paired with `convenienceFeeDisclosureAcknowledgedAt` and required on the same requests. Auth-time-only. nullablemax length 64
`convenienceFeeEligibilitySnapshot` required	string	Serialized convenience-fee eligibility decision (reason code + assessed amount) captured at disclosure-acknowledgment time. Codes / amounts only: no request- or response-derived free text (PCI). Gateway-produced and optional: the Virtual Terminal and Hosted Payment Page serialize their own fee decision into it, and a direct API integration has no equivalent internal decision to record, so it is never required. Auth-time-only. nullablemax length 2048
`convenienceFeeCancelledAmount` required	number (double)	The convenience-fee amount, in the transaction currency, the Virtual Terminal operator declined on the disclosure-confirm modal, removing it from this submission. Set by the VT cancel path (button, X, or Esc) so the authorization pipeline can record a `CsrCancelledVtModal` convenience-fee decision note carrying the amount that was waived: the fee is gone from the amounts by submit time, so the evaluator has nothing left to explain without this marker. Audit-only. It never adds to any total, never reaches the processor, and is honoured only when the submitted transaction carries no convenience fee, originates from the Virtual Terminal, and belongs to a merchant with an active convenience-fee configuration. Auth-time-only: the AutoMapper Update and recurring-billing maps both ignore it. `null` (the default) on every submission where no disclosed fee was cancelled. nullable
`surchargeDisclosureAcknowledgedAt` required	string (date-time)	UTC timestamp captured at the surcharge disclosure confirm-click moment (NOT at submit). Set by the Virtual Terminal confirm modal / HPP acceptance when a surcharge is disclosed and agreed. Auth-time-only: the AutoMapper Update and recurring-billing maps both ignore it so it cannot be set on subsequent operations. `null` when no surcharge disclosure was acknowledged. nullable
`surchargeDisclosureChannel` required	string	Channel on which the surcharge disclosure was acknowledged (`"VirtualTerminal"`, `"HostedPaymentPage"`, or `"Api"`). Paired with `surchargeDisclosureAcknowledgedAt`. Auth-time-only. nullable
`achWebAuthorizationText` required	string	The NACHA WEB single-debit authorization language shown to the payer, captured verbatim at ACH submit on the Hosted Payment Page. The consent evidence NACHA requires to substantiate an internet-initiated (WEB) ACH debit. Auth-time-only: the AutoMapper Update and recurring-billing maps both ignore it so it cannot be set on subsequent operations. `null` for non-ACH tenders. PCI-safe: authorization language only. nullable
`achWebAuthorizationTextVersion` required	string	Stable version hash (`sha256:{hex}`) of `achWebAuthorizationText`. Auth-time-only. nullable
`achWebAuthorizationConsumerIp` required	string	Consumer IP recorded at ACH WEB authorization time (required NACHA evidence). On the anonymous Hosted Payment Page create path the server derives this from the incoming request and ignores a caller-supplied value. Auth-time-only. `null` for non-ACH tenders. nullable
`achWebAuthorizationAt` required	string (date-time)	UTC timestamp of the ACH WEB authorization. Server-stamped on create; a client-supplied value is never trusted. Auth-time-only. `null` for non-ACH tenders. nullable
`achWebAuthorizationSecCode` required	string	SEC code the ACH WEB authorization was captured under (always `"WEB"` for HPP ACH). Auth-time-only. `null` for non-ACH tenders. nullable
`achAuthorizationAttested` required	boolean	Operator attestation signal for a Virtual Terminal CSR-keyed ACH debit: `true` when the operator confirmed they obtained the account holder's authorization (TEL or PPD) for the debit. This is a transient <b>input</b> only: the server consumes it to gate the submit (fail-closed when a VT ACH debit is not attested) and to stamp the persisted `AchAuthorization*` evidence fields; it is never persisted on its own. `null` / `false` for non-VT-ACH tenders and for callers that do not attest. nullable
`achAuthorizationStatementText` required	string	The CSR attestation statement captured for a Virtual Terminal CSR-keyed ACH debit (NACHA TEL / PPD). Server-owned: rendered from the selected SEC code and stamped at create time, never trusted from the client. Auth-time-only: the AutoMapper Update and recurring-billing maps both ignore it so it cannot be set on subsequent operations. `null` for non-VT-ACH tenders. PCI-safe: authorization language only. nullable
`achAuthorizationStatementVersion` required	string	Stable version hash (`sha256:{hex}`) of `achAuthorizationStatementText`. Server-recomputed from the statement text; a client-supplied value is never trusted. Auth-time-only. nullable
`achAuthorizationSecCode` required	string	SEC code the VT ACH authorization was captured under (`"TEL"` or `"PPD"`). Server-owned from the operator's selection on `CheckData.SecCode`. Auth-time-only. `null` for non-VT-ACH tenders. nullable
`achAuthorizationChannel` required	string	Channel on which the VT ACH authorization was attested (`"VirtualTerminal"`). Server-owned. Auth-time-only. `null` for non-VT-ACH tenders. nullable
`achAuthorizationAt` required	string (date-time)	UTC timestamp of the VT ACH authorization. Server-stamped on create; a client-supplied value is never trusted. Auth-time-only. `null` for non-VT-ACH tenders. nullable
`requestedSplitTenderTotal` required	number (double)	The total of the whole order, when you know before submitting that the customer will pay for it with more than one card. This transaction is charged for its own amount; once it is approved, it stays open as the first payment of a split tender collecting toward this total, and each further card is posted to `POST /api/transactions/{id}/split-tender/continuations`. Conditional: When RequestedSplitTenderTotal is not null. nullable

This request body has no documented fields.