WinkPG Docs
View as Markdown

llms.txt

The API reference isn't available right now

This instance couldn't load its API specification. The reference returns as soon as the specification is readable again.

Back to the API reference

No such operation

This instance documents no operation under that identifier. It may have been renamed, or it may belong to a feature this installation hasn't enabled.

Back to the API reference

This reference may be out of date

This instance couldn't reach its API specification on the last attempt, so this page shows the copy fetched before that. Anything added or changed since then is missing here, and the reference updates itself as soon as the specification is readable again. Last fetched 2026-10-22 22:09 UTC.

API reference Merchants

Promotes the specified merchant to the Production environment.

POST /api/merchants/{id}/promote deprecated

Requires: Merchants.Merchants.ManageEnvironment, merchant scope.

Requires API key scope: admin (Administration)

Records who promoted the merchant and when, on `PromotedAt` and `PromotedByUserId`. Promotable from Sandbox and Pending Promotion. A merchant already in Production is returned unchanged, so a repeated call is safe and does not restamp the original promotion. A suspended merchant is refused with 409 Conflict: extend its trial to return it to the sandbox first. The promotion also passes the two refusals that govern every other environment change: a merchant carrying an active loopback simulator profile, and a merchant under a reseller that restricts its merchants to the sandbox, are both refused with 409 Conflict. Every API key minted against this merchant while it was in a test environment stops authenticating once the promotion lands. The integrator must mint or rotate live keys. Promotion ends a trial: `TrialExpiresAt` and `TrialExpiryWarnedThresholdDays` are cleared, so the merchant receives no further trial reminders and is not suspended when the old deadline passes. `PlanCode` is kept.

Signed in, you can send this request to your own sandbox merchant from the console and read the answer. Sign in to try it.

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

Code sample language

cURL

curl -X POST "{{BASE_URL}}/api/merchants/{id}/promote" \
  -H "api-key: {{API_KEY}}"

PowerShell

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

$response = Invoke-RestMethod -Method POST -Uri '{{BASE_URL}}/api/merchants/{id}/promote' `
    -Headers $headers

npm install @winkpg/winkpg-api

TypeScript (SDK)

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

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

const { data } = await api.merchantsPromoteToProduction("3fa85f64-5717-4562-b3fc-2c963f66afa6");

TypeScript (raw HTTP)

const response = await fetch('{{BASE_URL}}/api/merchants/{id}/promote', {
  method: 'POST',
  headers: {
    "api-key": "{{API_KEY}}",
  },
});

const data = await response.json();

dotnet add package WinkPg.Api.Client

C# (SDK)

using WinkPg.Api.Client.Api;
using WinkPg.Api.Client.Client;

var config = new Configuration { BasePath = "{{BASE_URL}}" };
config.AddApiKey("api-key", "{{API_KEY}}");

var api = new MerchantsApi(config);
var result = await api.MerchantsPromoteToProductionAsync(Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6"));

C# (raw HTTP)

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

var request = new HttpRequestMessage(new HttpMethod("POST"), "/api/merchants/{id}/promote");
request.Headers.Add("api-key", "{{API_KEY}}");

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.MerchantsApi(client)
    result = api.merchants_promote_to_production("3fa85f64-5717-4562-b3fc-2c963f66afa6")

pip install requests

Python (raw HTTP)

import requests

headers = {
    "api-key": "{{API_KEY}}",
}

response = requests.request(
    "POST",
    "{{BASE_URL}}/api/merchants/{id}/promote",
    headers=headers,
)
response.raise_for_status()
data = response.json()

Parameters

Name In Type Description
id required path string (uuid) The unique identifier of the merchant to promote.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
suppressNulls required query boolean If true, omit properties with null values.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Request body

application/json , required

Field Type Description

This request body has no documented fields.

Responses

200 OK

Body: MerchantDto MerchantDto Each item has these fields.

Field Type Description
extraProperties required object nullableread only
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
id required string (uuid)
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
creationTime required string (date-time) The date and time when this entity was created.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
creatorId required string (uuid) The ID of the user who created this entity. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
lastModificationTime required string (date-time) The date and time when this entity was last modified. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
lastModifierId required string (uuid) The ID of the user who last modified this entity. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
isDeleted required boolean Indicates whether this entity has been deleted.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
deleterId required string (uuid) The ID of the user who deleted this entity, if it is deleted. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
deletionTime required string (date-time) The date and time when this entity was deleted, if it is deleted. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
createdFromTemplateId required string (uuid) The template this record was created from, or `null` for one started blank. Set by the create-from-template path and by the add/edit page's Load Template action when the record is saved. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
name required string Gets or sets the display name of the merchant. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
concurrencyStamp required string Gets or sets the concurrency stamp used for optimistic concurrency control. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
tenantId required string (uuid) Gets the tenant identifier for multi-tenancy isolation. nullableread only
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
resellerId required string (uuid) Gets or sets the unique identifier of the reseller that owns this merchant.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
resellerName required string Gets or sets the display name of the owning reseller. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
entityVersion required integer (int32) Gets the entity version number, incremented on each update for optimistic concurrency. read only
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
customIdentifier required string Gets or sets an optional custom identifier assigned to the merchant by the reseller or integrator. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
dba required string Gets or sets the "Doing Business As" (DBA) name for the merchant. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
legacyNumber required integer (int64) Gets the merchant's legacy numeric key, the integer identifier the v1 API addresses merchants by (its `MerchantKey`). Server-owned and stamped once at create; null on merchants written before the field existed until the v1 data migration back-fills them. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
mcc required string Gets or sets the four-character ISO 18245 Merchant Category Code identifying the merchant's industry. Null on legacy merchants that have not yet been backfilled; the merchant grid and detail view surface a warning indicator in that case so internal staff can address it. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
isTest required boolean Gets or sets a value indicating whether this merchant is a test account used for non-production transactions.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
environment required MerchantEnvironment MerchantEnvironment Gets or sets the merchant's lifecycle environment.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Sandbox The merchant transacts against the processor's test host. No live money moves. This is the fail-closed default for anything whose environment cannot be determined.
PendingPromotion The merchant has requested promotion to production and is awaiting approval. It may not transact against any endpoint while in this state.
Production The merchant transacts against the processor's live host. The only state that resolves a production endpoint.
Suspended The merchant has been administratively suspended. It may not transact against any endpoint, live or test, until it is returned to another state.
planCode required string Gets or sets the plan this merchant is on, or `null` when it is on none. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
trialExpiresAt required string (date-time) Gets or sets when this merchant's trial ends, UTC, or `null` when it is not on a time-limited plan. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
trialExpiryWarnedThresholdDays required integer (int32) Gets or sets the most recent trial expiry reminder sent in the current trial window, as the number of days before `trialExpiresAt` it was sent at. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
processorMode required MerchantProcessorMode MerchantProcessorMode Gets or sets which processor a sandbox merchant's transactions route to. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Loopback Route to the merchant's loopback processor profile. The loopback contributor is synthetic and performs no external I/O, so a sandbox merchant in this mode can be exercised end to end without any processor credentials.
ProcessorTest Route to a real processor profile, which the merchant's sandbox environment already pins to that processor's test host.
isActive required boolean Gets or sets a value indicating whether the merchant is currently active and able to process transactions.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
contactDetail required MerchantContactDetail MerchantContactDetail Gets or sets the merchant's contact details including addresses, phone numbers, and email.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of MerchantContactDetail:

Field Type Description
primaryContactName required string nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
emailAddress required string The contact's email address. Optional. A value that is not blank must be a valid email address. Conditional: When EmailAddress is not empty. Must be a valid email. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
phone required string The contact's phone number. Optional. A value that is not empty must be a phone number: digits, with an optional leading `+` and country code, optional parentheses around the area code, and a space, hyphen or period between groups. Letters, including an extension such as `x123`, are rejected. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
fax required string The contact's fax number. Optional. Follows the same rule as the phone number. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
companyUrl required string The company's website address. Optional. A value sent without a scheme, such as `www.example.com`, is stored with `https://` added. A value that starts with `http://` or `https://` is stored exactly as sent. Any other scheme, and text that is not a website address, is rejected. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
addresses required array of MerchantAddress array of MerchantAddress nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

businessInfo required MerchantBusinessInfo MerchantBusinessInfo Gets or sets the merchant's business information such as currency, tax IDs, and industry codes.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of MerchantBusinessInfo:

Field Type Description
federalTaxId required string nullablemax length 50
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
stateTaxId required string nullablemax length 50
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
salesTaxId required string nullablemax length 50
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
yearlySalesAmount required number (double) Conditional: When YearlySalesAmount is not null. Must be > 0. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
businessStartDate required string (date-time) nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
currency required string nullablemax length 3
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
ownershipType required OwnershipType OwnershipType nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Corporation
Partnership
LimitedPartnership
LimitedLiabilityPartnership
LimitedLiabilityCompany
CorporationSubchapter
IndividualOrSoleProprietor
Other

This body has no documented fields.

virtualTerminal required VirtualTerminalSettings VirtualTerminalSettings Gets or sets the virtual terminal field configuration for the merchant.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of VirtualTerminalSettings:

Field Type Description
cardBinPrompting required VirtualTerminalCardBinPrompting VirtualTerminalCardBinPrompting
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
allowRepeatSales required boolean
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
allowRefunds required boolean
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
enableEmailReceipts required boolean
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
fields required VirtualTerminalFields VirtualTerminalFields
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
allowPartialApprovals required boolean Merchant-level master switch for partial approvals. When false, no processor profile can enable partial approvals for this merchant; when true, each profile still decides per card type through its own partial-auth field. A merchant document written before this setting existed carries no value, which reads as the default (available). Conditional: When AllowPartialApprovals is false and CardBinPrompting is not null and CardBinPrompting.EnableFsa is true. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
partialApprovalStrategy required PartialApprovalStrategy PartialApprovalStrategy What the platform does with a partial approval. Null means unconfigured and resolves to `RequireOperatorAcknowledgment`. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
RequireOperatorAcknowledgment Hold the partial authorization and wait for an operator to accept the approved amount or void it. The platform takes no action of its own until the operator answers, or until partialApprovalAckTimeoutMinutes elapses.
AutoAccept Keep the approved amount without asking. The remainder is collected as a second tender when split tender is permitted, or left uncollected when it is not.
AutoVoid Void the partial authorization immediately and treat the sale as not completed. Use where a short payment is never acceptable and the cardholder should be asked for another card.
allowSplitTender required boolean Whether the remainder of a partially approved sale may be collected on a second tender. Null reads as the default (permitted). nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
allowTipAdjustmentOnPartialApproval required boolean Whether a tip may be adjusted on a transaction the issuer already reduced. Opt-in; null reads as the default (not permitted). Conditional: When AllowPartialApprovals is false and AllowTipAdjustmentOnPartialApproval is true. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
splitTenderMaxTenders required integer (int32) Maximum number of tenders a single sale may be split across. Null reads as the default (`DefaultSplitTenderMaxTenders`). Conditional: When AllowPartialApprovals is false and SplitTenderMaxTenders is not null. nullablemin 1max 4
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
partialApprovalAckTimeoutMinutes required integer (int32) How long the platform waits for an operator to accept or void a partial approval before the acknowledgment window closes. Only meaningful under `RequireOperatorAcknowledgment`. Null reads as the default (`DefaultPartialApprovalAckTimeoutMinutes`). Conditional: When PartialApprovalAckTimeoutMinutes is not null and PartialApprovalStrategy is not null and PartialApprovalStrategy != RequireOperatorAcknowledgment. nullablemin 1max 1440
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

processing required ProcessingSettingsDto ProcessingSettingsDto Gets or sets the processing settings including duplicate checks, card verification, and processor profiles.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of ProcessingSettingsDto:

Field Type Description
duplicateCheck required DuplicateCheckSettings DuplicateCheckSettings Gets or sets the duplicate transaction detection settings.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
orderDataDefaults required OrderDataDefaultSettings OrderDataDefaultSettings Gets or sets the default order data values applied to transactions when not explicitly provided.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
cardVerification required CardVerificationSettings CardVerificationSettings Gets or sets the AVS and CVV card verification settings that control transaction approval behavior.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
requireLevel2Data required boolean Gets or sets a value indicating whether card bins qualifying for level 2 processing are required to supply level 2 data (manually or via order data defaults).
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
requireNameOnCard required boolean Gets or sets a value indicating whether the cardholder name must be provided with the transaction regardless of entry mode.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
requireZipCode required boolean Gets or sets a value indicating whether the billing zip code must be provided with the transaction regardless of entry mode or AVS settings.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
requireShipping required boolean Gets or sets a value indicating whether the shipping amount must be provided with the transaction.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
enableForceCapture required boolean Gets or sets a value indicating whether force capture transactions are allowed for this merchant.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
requestProcessorToken required boolean Merchant preference for requesting a processor-issued reusable token at authorization time, referenced elsewhere as `Processing.RequestProcessorToken`. Tri-state: `null` (the default) means "auto", resolved ON wherever the routed processor advertises processor tokenization; `true` / `false` force the preference on or off. Surfaced on the merchant Processing tab as a tri-state selector (Auto / Always request / Never request); carried on the DTO so the value round-trips through the merchant create/update flow. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
enableCreateIdempotency required boolean Opt-in for caller-facing create idempotency on the transaction-create surface, referenced elsewhere as `Processing.EnableCreateIdempotency`. When `true`, a caller-supplied `idempotencyKey` on a create is validated and claimed, so a retried create returns the original transaction instead of charging again. `false` means off. `null` means the merchant sets no value and inherits its reseller's create-idempotency default; with no reseller default set, that resolves to off, as it always has. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
enhancedDataEnforcement required EnhancedDataEnforcementMode EnhancedDataEnforcementMode How hard the platform pushes back on a commercial-card sale whose enhanced data is unlikely to earn a Visa CEDP or Mastercard Data Rate interchange rate, referenced elsewhere as `Processing.EnhancedDataEnforcement`. `Off` (the default) changes nothing. `Warn` adds an `enhancedDataQualification` preview to the create response for a commercial card and shows the same findings in the Virtual Terminal. `Strict` refuses a commercial Visa or Mastercard sale that carries findings instead of capturing it. `null` means the merchant has expressed no preference and behaves as `Off`. Conditional: When EnhancedDataEnforcement is not null. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Off Nothing is added to a capture surface or a create response. The default, and what an unconfigured merchant resolves to.
Warn Findings are reported and the sale goes through: the create response carries a preview of the assessment, and the Virtual Terminal shows the warnings it already shows.
Strict A commercial Visa or Mastercard sale carrying findings is refused rather than captured. The Virtual Terminal blocks the submit and the API answers a validation error. Findings from the junk-data heuristics (a description that is the merchant name, a generic word, a single character, a pipe character) are reported but never refuse: they are advisory under every mode.
cardAcceptancePolicy required CardAcceptancePolicyDto CardAcceptancePolicyDto The cards this merchant is willing to take, judged from the card's BIN by funding source (credit, debit, prepaid), issued entity (consumer, commercial, GSA) and issuer country, referenced elsewhere as `Processing.CardAcceptancePolicy`. `null` (the default) accepts every card, which is what the platform did before this setting existed. Conditional: When CardAcceptancePolicy is not null.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
cashPolicy required CashPolicyDto CashPolicyDto The merchant's rules for cash sales and refunds, referenced elsewhere as `Processing.CashPolicy`. `null` (the default) applies no cash rule, which is what the platform did before this setting existed. Conditional: When CashPolicy is not null.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
taxShippingAmount required boolean Whether the auto-calculated tax on the Virtual Terminal and the hosted payment page is computed on the base amount plus the shipping amount. `null` (the default) and `false` compute it on the base amount alone. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
surchargeIncludesShipping required boolean Whether the surcharge percentage applies to the base amount plus the shipping amount. `null` (the default) and `false` apply it to the base amount alone. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
convenienceFeeIncludesShipping required boolean Whether a percentage convenience fee, and the percentage caps that bound it, apply to the base amount plus the shipping amount. `null` (the default) and `false` apply them to the base amount alone. A flat convenience fee is unaffected. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
taxGatewayFees required boolean Whether the auto-calculated tax on the Virtual Terminal and the hosted payment page includes the surcharge or convenience fee the page shows before the payment is submitted. `null` (the default) and `false` compute the tax without either fee. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
processorProfiles required array of ProcessorProfileDto array of ProcessorProfileDto Gets or sets the collection of processor profiles configured for this merchant. Each profile maps a payment processor and its supported payment types. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
screeningProviderProfiles required array of ScreeningProviderProfileDto array of ScreeningProviderProfileDto Gets or sets the external screening providers configured for this merchant. Each profile points at a registered screening provider and carries that provider's per-merchant field values. Conditional: When ScreeningProviderProfiles is not null. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
processorRoutingRuleSet required ProcessorRoutingRuleSetDto ProcessorRoutingRuleSetDto Gets or sets this merchant's conditional processor routing rule set: an ordered, first-match list of rules that send a transaction to one of the merchant's own processor accounts based on deterministic attributes of that transaction.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
autoSettlement required AutosettlementSettings AutosettlementSettings Gets or sets the auto-settlement configuration that controls automatic batch settlement behavior.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
registers required array of MerchantRegister array of MerchantRegister Gets or sets the collection of registers (point-of-sale terminals) assigned to this merchant. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

features required MerchantFeatureSettings MerchantFeatureSettings Gets or sets the feature flags and capability settings for the merchant.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of MerchantFeatureSettings:

Field Type Description
enableGsaBinCheck required boolean Ignored. Nothing reads this flag; the platform decides whether a government-issued card is accepted from the BIN through the merchant card acceptance policy (`CardAcceptancePolicy`), and the Virtual Terminal's GSA prompt is driven by `VirtualTerminal.CardBinPrompting.EnableGsa`. deprecated
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
enableAuthEdit required boolean
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
configurationLimits required MerchantConfigLimits MerchantConfigLimits
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
merchantBilling required MerchantBillingSettings MerchantBillingSettings
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
tenders required TenderEnableFlags TenderEnableFlags Per-tender enable flags applied by the capability cascade at the merchant layer. A merchant must explicitly opt in to each non-credit tender (EBT SNAP, EBT Cash, eWIC) before any of its processor accounts can accept it.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
enablePaymentTokenization required boolean Per-merchant override of the reseller-level payment tokenization flag (`paymentTokenization`). `null` means inherit the reseller default; `true`/`false` force-enables or disables tokenization for this merchant. The reseller flag always gates: a merchant cannot turn tokenization on if the reseller has not enabled it. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
hppTokenizeOnPaymentDefault required boolean Per-merchant default for whether a Hosted Payment Page session vaults the cardholder's card as a reusable `PaymentToken` on a successful payment, used when the session-create request does not explicitly set `TokenizeOnPayment`. `null` / `false` means do not tokenize by default; `true` opts the merchant's HPP sessions into tokenize-on-payment unless a session overrides it. The targeted page must still allow tokenization (Classic `SupportTokenization` / Streamlined `SavePaymentDetails`) and a tokenizing session must declare a stored-credential consent scope. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

capabilities required MerchantCapabilitiesDto MerchantCapabilitiesDto Gets or sets the read-only, server-computed capability flags derived from the merchant's configuration (e.g., active processor profiles' enabled tenders). Intended for UI affordance decisions; not enforced at submit time. Populated by the AutoMapper profile on read; not accepted on Create/Update.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of MerchantCapabilitiesDto:

Field Type Description
alternateCardTenders required AlternateCardTenderCapabilitiesDto AlternateCardTenderCapabilitiesDto Gets or sets the per-tender flags describing which alternate card tenders (EBT SNAP, EBT Cash, eWIC) at least one active processor profile is configured to accept.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

customFields required array of CustomField array of CustomField Gets or sets the collection of custom fields defined for the merchant. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of each CustomField:

Field Type Description
id required string (uuid)
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
name required string nullablemin length 3max length 50pattern ^[A-Za-z0-9]+(?:_[A-Za-z0-9]+)*$
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
notes required array of EntityNote array of EntityNote nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
tags required array of EntityTag array of EntityTag nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
isNumeric required boolean Conditional: When IsMultiValue is true.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
decimalPlaces required integer (int32) Conditional: When IsNumeric is true. Range: 0 to 2.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
maxLength required integer (int32) Conditional: When IsNumeric is false. Range: 0 to 300.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
regEx required string Conditional: When RegEx is not empty. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
regExErrorMessage required string Conditional: When RegExErrorMessage is not empty. Max length: 100. nullablemax length 100
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
isRequired required boolean
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
isEnabled required boolean
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
description required string Conditional: When Description is not empty. Max length: 100. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
numericMinValue required number (double) For numeric fields, the minimum value allowed. Negative minimums are permitted: a custom field is merchant-defined metadata rather than a monetary amount, so ranges that span or sit below zero (adjustments, offsets, deltas, temperatures) are legitimate. The value is inert unless `isNumeric` is set, and is validated only in that case. Conditional: When IsNumeric is true. Range: -1000000000 to 1000000000.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
numericMaxValue required number (double) For numeric fields, the maximum value allowed. It must be greater than or equal to `numericMinValue` but is not required to be positive, since a field whose whole range is negative is valid. The value is inert unless `isNumeric` is set, and is validated only in that case. Conditional: When IsNumeric is true. Range: -1000000000 to 1000000000.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
position required integer (int32) min 0
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
virtualTerminal required CustomFieldPresence CustomFieldPresence Presence settings for the Virtual Terminal, which collects this field from the operator when `visible` is set.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
hostedPaymentPage required CustomFieldPresence CustomFieldPresence
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
transactionReports required CustomFieldTransactionReportsPresence CustomFieldTransactionReportsPresence Presence settings for the surfaces that list a transaction's captured custom fields: the transaction detail page and the receipt. Only `visible` is honoured.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
showOnSaveCardSessions required boolean Whether this field is offered on a save-card hosted payment page session (one that stores the card without charging it). Defaults to off: most custom fields carry charge metadata (invoice number, purchase order, department) that is meaningless on a page whose only outcome is a stored card, so a field is suppressed on those sessions unless the merchant opts it in. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
legacyNumber required integer (int64) The integer key the v1 API addresses this definition by. Server-owned: allocated once, when the definition is first saved, and never reassigned afterwards. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
isMultiValue required boolean Whether a transaction carries a list of values for this field rather than a single value. A multi-value field is submitted through `TrxCustomField.Values`, prefilled on a hosted page session through `prefilledListFields`, and captured one value per line on the Virtual Terminal. The single `value` member keeps working on a multi-value definition: it is carried unchanged and mirrored into the list as its one item. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
maxValues required integer (int32) For a multi-value field, the largest number of values a transaction may carry. Unset reads as `DefaultMaxValues`; the platform ceiling is `MaxValuesCeiling`. Inert unless `isMultiValue` is set, and validated only in that case. Conditional: When IsMultiValue is true and MaxValues is not null. Range: 1 to 250. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

branding required MerchantBranding MerchantBranding Gets or sets the merchant-level branding configuration for receipts and customer-facing communications.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of MerchantBranding:

Field Type Description
logo required string Storage path to the merchant's logo image. The server resolves it to an absolute URL when it renders a receipt or other customer-facing content. nullablemin length 0max length 500
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
brandColor required string Hex color code used as the brand accent on receipts and customer-facing communications (e.g. "#1a1a1a"). nullablemin length 0max length 9
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
supportPhone required string Support phone number displayed on receipts. Overrides `phone` when present. nullablemin length 0max length 20
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
supportEmail required string Support email address displayed on receipts. Overrides `emailAddress` when present. nullablemin length 0max length 100
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
receiptFooterText required string Free-text footer message printed at the bottom of receipts (e.g. "Thank you for your business!"). nullablemin length 0max length 500
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
displayAddress required Address Address Display address shown on receipts. When null, falls back to the first address in `addresses`.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
termsAndConditions required string Terms and conditions of sale displayed on receipts (e.g. "No Refunds"). Required by Fiserv receipt compliance when the merchant has conditions of sale. nullablemin length 0max length 500
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

accountUpdater required AccountUpdaterSettingsDto AccountUpdaterSettingsDto Gets or sets the account updater configuration for this merchant.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of AccountUpdaterSettingsDto:

Field Type Description
isEnabled required boolean Whether account updater is enabled for this merchant. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
providerId required string Provider identifier (e.g., "tsys-ensurebill"). nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
providerName required string Human-readable provider display name. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
processingMode required string Processing mode as string ("Express" or "Batch"). nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
autoApplyUpdates required boolean Whether to automatically apply card updates. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
autoApplyExpirationOnly required boolean If true, only auto-apply expiration changes; hold PAN changes for review. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
notificationEnabled required boolean Whether email notifications are enabled. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
notificationEmailAddresses required array of string array of Notification email addresses. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
maxBatchSize required integer (int32) Maximum cards per batch. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
providerFieldValues required array of AccountUpdaterFieldValueDto array of AccountUpdaterFieldValueDto Provider-specific configuration field values. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

merchantFlowConfig required MerchantFlowConfig MerchantFlowConfig Gets or sets the optional transaction flow configuration that controls how transactions are orchestrated for this merchant.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of MerchantFlowConfig:

Field Type Description
id required string (uuid) Identifier of the flow configuration. Assigned by the platform. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
name required string Display name of the flow configuration. Optional and not used for matching. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
screening required FraudScreeningConfig FraudScreeningConfig Transaction screening configuration for this merchant. Null or absent leaves every screening rule unconfigured, which screens nothing.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

billingAssignment required MerchantBillingAssignment MerchantBillingAssignment Gets or sets the billing plan assignment for this merchant. A null value means the merchant has no active billing plan and will be skipped by billing runs.
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of MerchantBillingAssignment:

Field Type Description
pricePlanId required string (uuid) The price plan currently assigned to this merchant. Null means the merchant has no active billing plan and will be skipped by billing runs. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
effectiveFrom required string (date-time) Optional start date for the assignment. Billing runs prior to this date will skip the merchant. Null means effective immediately on assign. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
effectiveTo required string (date-time) Optional end date for the assignment. Billing runs after this date will skip the merchant. Null means open-ended. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
fulfillmentPath required BillingFulfillmentPath BillingFulfillmentPath Optional per-merchant override of the fulfillment path. When null the resolver inherits `defaultFulfillmentPath`. Only the path itself is overridable: collection plumbing (HPP id, collection merchant, payment-method allowlist) is reseller-level only and is never re-picked per assignment. This is a deliberate scope call to avoid re-introducing the legacy House Merchant per-assignment friction. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Invoicing Generate an invoice in PhoeniXGate.Invoicing addressed to the Merchant and route payment through the reseller's configured Hosted Payment Page.
RecurringContract Charge a stored payment method (card or ACH) against the Merchant on a schedule, via a recurring contract owned by the reseller's collection merchant.

This body has no documented fields.

notes required array of EntityNote array of EntityNote Gets or sets operational notes attached to the merchant. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of each EntityNote:

Field Type Description
id required string (uuid)
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
enteredBy required string (uuid)
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
timestamp required string (date-time)
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
enteredByName required string Denormalized display name of the user who created the note. Populated at creation time from `ICurrentUser` to avoid N+1 lookups when rendering. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
content required string nullablemin length 0max length 1000
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

saveWarnings required array of MerchantSaveWarning array of MerchantSaveWarning Non-blocking informational warnings produced by the most recent create/update of this merchant (e.g. international-AVS-on-US-only-surface advisories). `null` on read responses, populated (possibly with an empty list) on create/update responses, so clients can distinguish "this isn't a save response" (omitted from JSON via `WhenWritingDefault`) from "saved successfully with no warnings" (empty array). Not persisted. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of each MerchantSaveWarning:

Field Type Description
code required string Stable machine-readable identifier of the rule that produced the warning. For card- verification surface warnings this is the property name on `CardVerificationSettings` (e.g. `"AvNoMatchIntl"`). nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
propertyName required string Dotted path to the field the warning applies to, suitable for UI field highlighting (e.g. `"Processing.CardVerification.AvNoMatchIntl"`). May be empty when the warning is not anchored to a single field. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
message required string Human-readable message describing the condition for this specific warning. Should be short and code-specific; shared rationale common to a group of warnings belongs in `groupRationale` so renderers can emit it once per group. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
groupRationale required string Optional explanation shared by every warning a rule produces. When present, renderers MAY collapse warnings with an equal `groupRationale` into one shared paragraph plus a flat list of `code` values, rather than repeating the rationale inside every `message`. Null when the warning stands alone. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

volumeTrend required array of number (double) array of Metered transaction count per calendar month for this merchant, oldest to newest, as an activity trend. `null` on every response that does not populate it (which is all of them except the merchant list), so it is omitted from JSON entirely rather than serialized as null. Not persisted. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
digitalWallets required array of MerchantDigitalWallet array of MerchantDigitalWallet Gets or sets the per-merchant digital wallet bindings (Apple Pay, Google Pay, …). At most one entry per `WalletProviderType`; each carries the master enable flag and a pointer to the `WalletProviderRegistration` row this merchant uses (platform-level or merchant-level). nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of each MerchantDigitalWallet:

Field Type Description
walletProviderType required WalletProviderType WalletProviderType Which wallet this entry describes (Apple Pay, Google Pay, …). nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Unknown Unknown wallet provider.
ApplePay Apple Pay wallet provider.
GooglePay Google Pay wallet provider.
NetworkToken Network tokenization provider (Visa, Mastercard etc).
Paze Paze (Early Warning) wallet provider.
isEnabled required boolean Master enable flag for this wallet on this merchant. When `false` or null, the merchant's checkout surfaces must skip this wallet even if a registration row exists. Toggle is operator-controlled on the Merchant Edit page and persists with the Merchant save. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
paymentTokenizationRegistrationId required string (uuid) FK to the PaymentTokenization aggregate row this merchant uses. May point at a platform-level row (inheriting) or a merchant-level row (own integrator). Nullable so a merchant can be marked enabled before the operator picks / registers a specific row, and so a deleted registration leaves an inspectable "dangling but disabled" state rather than a hard reference. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

threeDSBindings required array of MerchantThreeDSBinding array of MerchantThreeDSBinding Gets or sets the per-merchant 3-D Secure provider bindings. At most one entry per `ThreeDSProviderType`; each carries the master enable flag, the policy mode, and the vendor credentials. <b>The JWT secret is never populated on a read.</b> It is stripped server-side before this DTO leaves the application service, so a caller sees null there whether or not one is stored. Sending null or an empty string back on a save keeps the stored secret; sending a value replaces it. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of each MerchantThreeDSBinding:

Field Type Description
providerType required ThreeDSProviderType ThreeDSProviderType Which 3-D Secure provider this entry binds the merchant to. A null provider type is treated as no binding at all rather than as `Fake`, so an incompletely boarded row cannot silently become a live selection. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Fake Deterministic in-memory provider that performs no network calls. The local-dev, CI, and default-selection provider, and the safe landing spot for an absent configuration value.
Paay Paay (API brand "3DS Integrator"), reached over its Direct API. Supports authentication, the 3DS Method step, the cardholder challenge, and 3RI; it documents no decoupled or Secure Payment Confirmation capability, so the registry refuses those.
isEnabled required boolean Master enable flag for this provider on this merchant. When `false` or null, the binding is not used even though the row exists. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
policyMode required ThreeDSPolicyMode ThreeDSPolicyMode How hard the merchant wants authentication applied. Null means the platform default, which callers read as `Off`. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Off Do not attempt 3-D Secure at all. The safe landing spot for an absent stored value.
Attempt Attempt authentication, but continue with the payment when it cannot be completed. Liability shift is taken where the issuer grants it and forgone where it does not.
Require Attempt authentication and refuse the payment when it cannot be completed. The merchant has chosen never to process an unauthenticated transaction on the surfaces this applies to.
apiKey required string The vendor API key. Not a secret in the sense the JWT secret is (it is sent as a request header and appears as a JWT audience), so it round-trips on reads; it is still never logged. Required: When IsEnabled is true. nullablemax length 256
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
jwtSecret required string The shared secret the request JWT is signed with. <b>Stored encrypted.</b> It is stripped, not decrypted, on every read that leaves the server: the admin UI and the API both see null here and re-send the secret only when the operator changes it. Only the server-side call to the provider ever uses the plaintext. nullablemax length 512
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
jwtSecretConfigured required boolean Whether a JWT secret is stored for this binding, for the editor that is never allowed to see the secret itself. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
endpointEnvironment required ThreeDSEndpointEnvironment ThreeDSEndpointEnvironment Which of the vendor's environments this binding points at. Null reads as `Sandbox`. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Sandbox The vendor's test environment. The safe landing spot for an absent stored value.
Live The vendor's production environment.
requestorUrl required string The merchant-facing origin the vendor validates authentication requests against: the HPP or checkout origin the cardholder's browser is on. HTTPS only. Conditional: When RequestorUrl is not empty. Required: When IsEnabled is true. nullablemax length 512
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
challengeEnabled required boolean Whether the merchant permits the vendor to raise an interactive challenge. Null reads as not enabled. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
protocolVersion required string The 3-D Secure protocol version to request, from `SupportedProtocolVersions`. Null means the provider's own default. Conditional: When ProtocolVersion is not empty. nullablemax length 16
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
providerRegistrationId required string (uuid) Optional pointer at a vendor-side registration record for this merchant, for vendors that board a merchant out of band and hand back an identifier. Nullable because most bindings carry credentials and nothing else, and because a deleted registration should leave an inspectable dangling reference rather than a hard failure. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

taxBindings required array of MerchantTaxBinding array of MerchantTaxBinding Gets or sets the per-merchant tax provider bindings. At most one entry per provider name; each carries the master enable flag, whose provider account the lookups are billed to, and the provider's configuration values. <b>Secret field values are never populated on a read.</b> They are stripped server-side before this DTO leaves the application service, and each field reports `isConfigured` instead so an operator can tell a stored secret from an empty one. Sending null or an empty string back on a save keeps the stored secret; sending a value replaces it. A binding whose credential source is `Gateway` carries no values at all: the gateway's own provider credentials are never copied onto a merchant, and are resolved at lookup time instead. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of each MerchantTaxBinding:

Field Type Description
providerName required string Which tax provider this entry binds the merchant to, by the provider's registered name. Compared case-insensitively. A null or blank provider is treated as no binding at all, so an incompletely boarded row cannot silently become a live selection. Required: When IsEnabled is true. nullablemax length 64
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
isEnabled required boolean Master enable flag for this provider on this merchant. When `false` or null, the selector must not return this binding even though the row exists. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
credentialSource required TaxCredentialSource TaxCredentialSource Whose provider account the lookups are billed to. Null reads as `Gateway`. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Gateway The gateway's own provider account. The binding stores no credential of its own: the values are filled in at read time from the host-scoped provider settings, and the merchant surfaces never carry them. This is what a null credentialSource reads as, which is the safe default: a half-completed row cannot accidentally claim to hold the merchant's own contract.
Merchant The merchant's own provider account. The binding carries the credentials, with every secret value held as ciphertext and stripped on any read that leaves the server.
fieldValues required array of TaxBindingFieldValue array of TaxBindingFieldValue The provider-declared configuration values for this merchant, keyed by the setting names the provider declares. <b>Secret values are stored encrypted</b> and are stripped, not decrypted, on every read that leaves the server: the admin UI and the API both see null and re-send a secret only when the operator changes it. Only the server-side call to the provider ever uses the plaintext. Empty for a `Gateway` binding, whose values are filled in at read time from the host-scoped provider settings instead. A gateway-sourced row that carried values would be a copy of the gateway's key living on a merchant document. Conditional: When FieldValues is not null. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
defaultCountryCode required string The country code to use for a lookup that does not name one. Null falls back to the gateway-wide `TaxCalculation.DefaultCountryCode` setting. nullablemax length 3
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

shippingBindings required array of MerchantShippingBinding array of MerchantShippingBinding Gets or sets the per-merchant shipping rate provider bindings. At most one entry per provider name; each carries the master enable flag, whose provider account the quotes are billed to, and the provider's configuration values. <b>Secret field values are never populated on a read.</b> They are stripped server-side before this DTO leaves the application service, and each field reports `isConfigured` instead so an operator can tell a stored secret from an empty one. Sending null or an empty string back on a save keeps the stored secret; sending a value replaces it. A binding whose credential source is `Gateway` carries no values at all: the gateway's own provider credentials are never copied onto a merchant, and are resolved at quote time instead. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of each MerchantShippingBinding:

Field Type Description
providerName required string Which shipping provider this entry binds the merchant to, by the provider's registered name. Compared case-insensitively. A null or blank provider is treated as no binding at all, so an incompletely boarded row cannot silently become a live selection. Required: When IsEnabled is true. nullablemax length 64
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
isEnabled required boolean Master enable flag for this provider on this merchant. When `false` or null, the selector must not return this binding even though the row exists. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
credentialSource required ProviderCredentialSource ProviderCredentialSource Whose provider account the quotes are billed to. Null reads as `Gateway`. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Gateway The gateway's own provider account. The binding stores no credential of its own: the values are filled in at read time from the host-scoped provider settings, and the merchant surfaces never carry them. This is what a null credential source reads as, which is the safe default: a half-completed row cannot accidentally claim to hold the merchant's own contract.
Merchant The merchant's own provider account. The binding carries the credentials, with every secret value held as ciphertext and stripped on any read that leaves the server.
fieldValues required array of ShippingBindingFieldValue array of ShippingBindingFieldValue The provider-declared configuration values for this merchant, keyed by the setting names the provider declares. For a provider whose gateway credentials are platform-wide settings, the keys are those same setting names, so one name identifies a credential whoever holds it. <b>Secret values are stored encrypted</b> and are stripped, not decrypted, on every read that leaves the server: the admin UI and the API both see null and re-send a secret only when the operator changes it. Only the server-side call to the provider ever uses the plaintext. Empty for a `Gateway` binding, whose values are filled in at read time from the host-scoped provider settings instead. A gateway-sourced row that carried values would be a copy of the gateway's token living on a merchant document. Conditional: When FieldValues is not null. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

paymentEncryptionBindings required array of MerchantPaymentEncryptionBinding array of MerchantPaymentEncryptionBinding Gets or sets the per-merchant payment encryption provider bindings. At most one entry per provider name; each carries the master enable flag, whose provider account the decryption calls are billed to, the provider's configuration values, and the key serial identifier table. <b>Secret field values and key references are never populated on a read.</b> They are stripped server-side before this DTO leaves the application service. Each field reports `isConfigured` and each key entry reports `isKeyReferenceConfigured` in their place, so an operator can tell a stored value from an empty one. Sending null or an empty string back on a save keeps the stored value; sending a value replaces it. A binding whose credential source is `Gateway` carries no field values at all: the gateway's own provider credentials are never copied onto a merchant, and are resolved at decryption time instead. Key entries are the merchant's either way, because a key serial identifier maps that merchant's own device fleet. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of each MerchantPaymentEncryptionBinding:

Field Type Description
providerName required string Which payment encryption provider this entry binds the merchant to, by the provider's registered name. Compared case-insensitively. A null or blank provider is treated as no binding at all, so an incompletely boarded row cannot silently become a live selection. Required: When IsEnabled is true. nullablemax length 64
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
isEnabled required boolean Master enable flag for this provider on this merchant. When `false` or null, the selector must not return this binding even though the row exists. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
credentialSource required PaymentEncryptionCredentialSource PaymentEncryptionCredentialSource Whose provider account the decryption calls are billed to. Null reads as `Gateway`. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Gateway The gateway's own provider account. The binding stores no credential of its own: the values are filled in at read time from the host-scoped provider settings, and the merchant surfaces never carry them. This is what a null credentialSource reads as, which is the safe default: a half-completed row cannot accidentally claim to hold the merchant's own contract.
Merchant The merchant's own provider account. The binding carries the credentials, with every secret value held as ciphertext and stripped on any read that leaves the server.
fieldValues required array of PaymentEncryptionBindingFieldValue array of PaymentEncryptionBindingFieldValue The provider-declared configuration values for this merchant, keyed by the setting names the provider declares. <b>Secret values are stored encrypted</b> and are stripped, not decrypted, on every read that leaves the server. Only the server-side call to the provider ever uses the plaintext. Empty for a `Gateway` binding, whose values are filled in at read time from the host-scoped provider settings instead. A gateway-sourced row that carried values would be a copy of the gateway's credentials living on a merchant document. Conditional: When FieldValues is not null. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
keyEntries required array of PaymentEncryptionKeyEntry array of PaymentEncryptionKeyEntry The key serial identifier entries that map an inbound key serial number to an HSM key. Conditional: When KeyEntries is not null. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
primaryEndpoint required string The primary provider endpoint for this merchant, or null to use the provider's own configured endpoint. HTTPS-only, enforced by the binding validator. Conditional: When PrimaryEndpoint is not empty. nullablemax length 512
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
secondaryEndpoint required string The secondary provider endpoint, used when the primary does not answer. HTTPS-only. Null when the merchant is bound to one region only. Conditional: When SecondaryEndpoint is not empty. Conditional: When SecondaryEndpoint is not empty and PrimaryEndpoint is empty. nullablemax length 512
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
decryptTimeoutMillisecondsOverride required integer (int32) A per-merchant override of the gateway-wide decryption budget, in milliseconds, or null to use the gateway setting. Conditional: When DecryptTimeoutMillisecondsOverride is not null. Range: 250 to 30000. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

promotedAt required string (date-time) When this merchant was promoted to `Production` through the promotion action, UTC. Null for a merchant that has never been promoted that way. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
promotedByUserId required string (uuid) The user who ran the promotion that stamped `promotedAt`, or null when the merchant has never been promoted through that action. nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
isLocked required boolean nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
lockedAt required string (date-time) nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
lockedByUserId required string (uuid) nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
lockedByUserName required string nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
lockReason required string nullable
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

403 Forbidden

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description
error required RemoteServiceErrorInfo RemoteServiceErrorInfo
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

401 Unauthorized

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description
error required RemoteServiceErrorInfo RemoteServiceErrorInfo
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

400 Bad Request

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description
error required RemoteServiceErrorInfo RemoteServiceErrorInfo
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

404 Not Found

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description
error required RemoteServiceErrorInfo RemoteServiceErrorInfo
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

501 Not Implemented

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description
error required RemoteServiceErrorInfo RemoteServiceErrorInfo
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

500 Internal Server Error

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description
error required RemoteServiceErrorInfo RemoteServiceErrorInfo
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

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 lists the values `error.code` can take. 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 lists the values `error.code` can take.

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description
error required RemoteServiceErrorInfo RemoteServiceErrorInfo
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

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.

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description
error required RemoteServiceErrorInfo RemoteServiceErrorInfo
Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

Errors

A failed request returns the platform error envelope. The error reference lists every value error.code can carry and shows the four response shapes.

Codes declared by Merchants

Authentication

    Reconnecting to the server

    Could not reconnect

    This session has ended

    Attempt 1

    Your work on this page is still here. Retrying keeps it; reloading starts the page again.

    The server no longer holds this page's state, so it has to be loaded again.