# POST /api/merchants/{id}/unlock Unlocks the specified merchant, allowing modifications and deletions again. **Required permissions**: `Merchants.Unlock` **Scope**: merchant **Operation ID:** `merchantsUnlock` ## Authorization Requires: Merchants.Merchants.Unlock, merchant scope. Requires API key scope: `admin` Required permissions: - `Merchants.Merchants.Unlock` ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | id | path | yes | string(uuid) | The unique identifier of the merchant to unlock. | | suppressNulls | query | no | boolean | If true, omit properties with null values. | ## Responses ### 200 OK **Content type:** `application/json` Schema: [`MerchantDto`](https://devportal.demo.winkpg.io/docs/api/models/MerchantDto.md) Properties: - `extraProperties` (object): (nullable, read only) - `id` (string(uuid)) - `creationTime` (string(date-time)): The date and time when this entity was created. - `creatorId` (string(uuid)): The ID of the user who created this entity. (nullable) - `lastModificationTime` (string(date-time)): The date and time when this entity was last modified. (nullable) - `lastModifierId` (string(uuid)): The ID of the user who last modified this entity. (nullable) - `isDeleted` (boolean): Indicates whether this entity has been deleted. - `deleterId` (string(uuid)): The ID of the user who deleted this entity, if it is deleted. (nullable) - `deletionTime` (string(date-time)): The date and time when this entity was deleted, if it is deleted. (nullable) - `createdFromTemplateId` (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) - `name` (string): Gets or sets the display name of the merchant. (nullable) - `concurrencyStamp` (string): Gets or sets the concurrency stamp used for optimistic concurrency control. (nullable) - `tenantId` (string(uuid)): Gets the tenant identifier for multi-tenancy isolation. (nullable, read only) - `resellerId` (string(uuid)): Gets or sets the unique identifier of the reseller that owns this merchant. - `resellerName` (string): Gets or sets the display name of the owning reseller. (nullable) - `entityVersion` (integer(int32)): Gets the entity version number, incremented on each update for optimistic concurrency. (read only) - `customIdentifier` (string): Gets or sets an optional custom identifier assigned to the merchant by the reseller or integrator. (nullable) - `dba` (string): Gets or sets the "Doing Business As" (DBA) name for the merchant. (nullable) - `legacyNumber` (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) - `mcc` (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) - `isTest` (boolean): Gets or sets a value indicating whether this merchant is a test account used for non-production transactions. - `environment` ([MerchantEnvironment](https://devportal.demo.winkpg.io/docs/api/models/MerchantEnvironment.md)): Gets or sets the merchant's lifecycle environment. Values: - `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` (string): Gets or sets the plan this merchant is on, or `null` when it is on none. (nullable) - `trialExpiresAt` (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) - `trialExpiryWarnedThresholdDays` (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) - `processorMode` ([MerchantProcessorMode](https://devportal.demo.winkpg.io/docs/api/models/MerchantProcessorMode.md)): Gets or sets which processor a sandbox merchant's transactions route to. (nullable) Values: - `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` (boolean): Gets or sets a value indicating whether the merchant is currently active and able to process transactions. - `contactDetail` ([MerchantContactDetail](https://devportal.demo.winkpg.io/docs/api/models/MerchantContactDetail.md)): Gets or sets the merchant's contact details including addresses, phone numbers, and email. Fields: - `primaryContactName` (string) required: (nullable) - `emailAddress` (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) - `phone` (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) - `fax` (string): The contact's fax number. Optional. Follows the same rule as the phone number. (nullable) - `companyUrl` (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) - `addresses` (array<[MerchantAddress](https://devportal.demo.winkpg.io/docs/api/models/MerchantAddress.md)>) required: (nullable) - `businessInfo` ([MerchantBusinessInfo](https://devportal.demo.winkpg.io/docs/api/models/MerchantBusinessInfo.md)): Gets or sets the merchant's business information such as currency, tax IDs, and industry codes. Fields: - `federalTaxId` (string): (nullable, max length 50) - `stateTaxId` (string): (nullable, max length 50) - `salesTaxId` (string): (nullable, max length 50) - `yearlySalesAmount` (number(double)): Conditional: When YearlySalesAmount is not null. Must be > 0. (nullable) - `businessStartDate` (string(date-time)): (nullable) - `currency` (string): (nullable, max length 3) - `ownershipType` ([OwnershipType](https://devportal.demo.winkpg.io/docs/api/models/OwnershipType.md)): (nullable) Values: - `Corporation` - `Partnership` - `LimitedPartnership` - `LimitedLiabilityPartnership` - `LimitedLiabilityCompany` - `CorporationSubchapter` - `IndividualOrSoleProprietor` - `Other` - `virtualTerminal` ([VirtualTerminalSettings](https://devportal.demo.winkpg.io/docs/api/models/VirtualTerminalSettings.md)): Gets or sets the virtual terminal field configuration for the merchant. Fields: - `cardBinPrompting` ([VirtualTerminalCardBinPrompting](https://devportal.demo.winkpg.io/docs/api/models/VirtualTerminalCardBinPrompting.md)) - `allowRepeatSales` (boolean) - `allowRefunds` (boolean) - `enableEmailReceipts` (boolean) - `fields` ([VirtualTerminalFields](https://devportal.demo.winkpg.io/docs/api/models/VirtualTerminalFields.md)) - `allowPartialApprovals` (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) - `partialApprovalStrategy` ([PartialApprovalStrategy](https://devportal.demo.winkpg.io/docs/api/models/PartialApprovalStrategy.md)): What the platform does with a partial approval. Null means unconfigured and resolves to `RequireOperatorAcknowledgment`. (nullable) Values: - `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` (boolean): Whether the remainder of a partially approved sale may be collected on a second tender. Null reads as the default (permitted). (nullable) - `allowTipAdjustmentOnPartialApproval` (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) - `splitTenderMaxTenders` (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. (nullable, min 1, max 4) - `partialApprovalAckTimeoutMinutes` (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. (nullable, min 1, max 1440) - `processing` ([ProcessingSettingsDto](https://devportal.demo.winkpg.io/docs/api/models/ProcessingSettingsDto.md)): Gets or sets the processing settings including duplicate checks, card verification, and processor profiles. Fields: - `duplicateCheck` ([DuplicateCheckSettings](https://devportal.demo.winkpg.io/docs/api/models/DuplicateCheckSettings.md)): Gets or sets the duplicate transaction detection settings. - `orderDataDefaults` ([OrderDataDefaultSettings](https://devportal.demo.winkpg.io/docs/api/models/OrderDataDefaultSettings.md)): Gets or sets the default order data values applied to transactions when not explicitly provided. - `cardVerification` ([CardVerificationSettings](https://devportal.demo.winkpg.io/docs/api/models/CardVerificationSettings.md)): Gets or sets the AVS and CVV card verification settings that control transaction approval behavior. - `requireLevel2Data` (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). - `requireNameOnCard` (boolean): Gets or sets a value indicating whether the cardholder name must be provided with the transaction regardless of entry mode. - `requireZipCode` (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. - `requireShipping` (boolean): Gets or sets a value indicating whether the shipping amount must be provided with the transaction. - `enableForceCapture` (boolean): Gets or sets a value indicating whether force capture transactions are allowed for this merchant. - `requestProcessorToken` (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) - `enableCreateIdempotency` (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) - `enhancedDataEnforcement` ([EnhancedDataEnforcementMode](https://devportal.demo.winkpg.io/docs/api/models/EnhancedDataEnforcementMode.md)): 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: - `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` ([CardAcceptancePolicyDto](https://devportal.demo.winkpg.io/docs/api/models/CardAcceptancePolicyDto.md)): 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. - `cashPolicy` ([CashPolicyDto](https://devportal.demo.winkpg.io/docs/api/models/CashPolicyDto.md)): 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. - `taxShippingAmount` (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) - `surchargeIncludesShipping` (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) - `convenienceFeeIncludesShipping` (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) - `taxGatewayFees` (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) - `processorProfiles` (array<[ProcessorProfileDto](https://devportal.demo.winkpg.io/docs/api/models/ProcessorProfileDto.md)>): Gets or sets the collection of processor profiles configured for this merchant. Each profile maps a payment processor and its supported payment types. (nullable) - `screeningProviderProfiles` (array<[ScreeningProviderProfileDto](https://devportal.demo.winkpg.io/docs/api/models/ScreeningProviderProfileDto.md)>): 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) - `processorRoutingRuleSet` ([ProcessorRoutingRuleSetDto](https://devportal.demo.winkpg.io/docs/api/models/ProcessorRoutingRuleSetDto.md)): 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. - `autoSettlement` ([AutosettlementSettings](https://devportal.demo.winkpg.io/docs/api/models/AutosettlementSettings.md)): Gets or sets the auto-settlement configuration that controls automatic batch settlement behavior. - `registers` (array<[MerchantRegister](https://devportal.demo.winkpg.io/docs/api/models/MerchantRegister.md)>): Gets or sets the collection of registers (point-of-sale terminals) assigned to this merchant. (nullable) - `features` ([MerchantFeatureSettings](https://devportal.demo.winkpg.io/docs/api/models/MerchantFeatureSettings.md)): Gets or sets the feature flags and capability settings for the merchant. Fields: - `enableGsaBinCheck` (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) - `enableAuthEdit` (boolean) - `configurationLimits` ([MerchantConfigLimits](https://devportal.demo.winkpg.io/docs/api/models/MerchantConfigLimits.md)) - `merchantBilling` ([MerchantBillingSettings](https://devportal.demo.winkpg.io/docs/api/models/MerchantBillingSettings.md)) - `tenders` ([TenderEnableFlags](https://devportal.demo.winkpg.io/docs/api/models/TenderEnableFlags.md)): 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. - `enablePaymentTokenization` (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) - `hppTokenizeOnPaymentDefault` (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) - `capabilities` ([MerchantCapabilitiesDto](https://devportal.demo.winkpg.io/docs/api/models/MerchantCapabilitiesDto.md)): 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. Fields: - `alternateCardTenders` ([AlternateCardTenderCapabilitiesDto](https://devportal.demo.winkpg.io/docs/api/models/AlternateCardTenderCapabilitiesDto.md)): 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. - `customFields` (array<[CustomField](https://devportal.demo.winkpg.io/docs/api/models/CustomField.md)>): Gets or sets the collection of custom fields defined for the merchant. (nullable) Fields of each item: - `id` (string(uuid)) - `name` (string) required: (nullable, min length 3, max length 50, pattern ^[A-Za-z0-9]+(?:_[A-Za-z0-9]+)*$) - `notes` (array<[EntityNote](https://devportal.demo.winkpg.io/docs/api/models/EntityNote.md)>): (nullable) - `tags` (array<[EntityTag](https://devportal.demo.winkpg.io/docs/api/models/EntityTag.md)>): (nullable) - `isNumeric` (boolean): Conditional: When IsMultiValue is true. - `decimalPlaces` (integer(int32)): Conditional: When IsNumeric is true. Range: 0 to 2. - `maxLength` (integer(int32)): Conditional: When IsNumeric is false. Range: 0 to 300. - `regEx` (string): Conditional: When RegEx is not empty. (nullable) - `regExErrorMessage` (string): Conditional: When RegExErrorMessage is not empty. Max length: 100. (nullable, max length 100) - `isRequired` (boolean) - `isEnabled` (boolean) - `description` (string): Conditional: When Description is not empty. Max length: 100. (nullable) - `numericMinValue` (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. - `numericMaxValue` (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. - `position` (integer(int32)): (min 0) - `virtualTerminal` ([CustomFieldPresence](https://devportal.demo.winkpg.io/docs/api/models/CustomFieldPresence.md)): Presence settings for the Virtual Terminal, which collects this field from the operator when `visible` is set. - `hostedPaymentPage` ([CustomFieldPresence](https://devportal.demo.winkpg.io/docs/api/models/CustomFieldPresence.md)) - `transactionReports` ([CustomFieldTransactionReportsPresence](https://devportal.demo.winkpg.io/docs/api/models/CustomFieldTransactionReportsPresence.md)): Presence settings for the surfaces that list a transaction's captured custom fields: the transaction detail page and the receipt. Only `visible` is honoured. - `showOnSaveCardSessions` (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) - `legacyNumber` (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) - `isMultiValue` (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) - `maxValues` (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) - `branding` ([MerchantBranding](https://devportal.demo.winkpg.io/docs/api/models/MerchantBranding.md)): Gets or sets the merchant-level branding configuration for receipts and customer-facing communications. Fields: - `logo` (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. (nullable, min length 0, max length 500) - `brandColor` (string): Hex color code used as the brand accent on receipts and customer-facing communications (e.g. "#1a1a1a"). (nullable, min length 0, max length 9) - `supportPhone` (string): Support phone number displayed on receipts. Overrides `phone` when present. (nullable, min length 0, max length 20) - `supportEmail` (string): Support email address displayed on receipts. Overrides `emailAddress` when present. (nullable, min length 0, max length 100) - `receiptFooterText` (string): Free-text footer message printed at the bottom of receipts (e.g. "Thank you for your business!"). (nullable, min length 0, max length 500) - `displayAddress` ([Address](https://devportal.demo.winkpg.io/docs/api/models/Address.md)): Display address shown on receipts. When null, falls back to the first address in `addresses`. - `termsAndConditions` (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. (nullable, min length 0, max length 500) - `accountUpdater` ([AccountUpdaterSettingsDto](https://devportal.demo.winkpg.io/docs/api/models/AccountUpdaterSettingsDto.md)): Gets or sets the account updater configuration for this merchant. Fields: - `isEnabled` (boolean): Whether account updater is enabled for this merchant. (nullable) - `providerId` (string): Provider identifier (e.g., "tsys-ensurebill"). (nullable) - `providerName` (string): Human-readable provider display name. (nullable) - `processingMode` (string): Processing mode as string ("Express" or "Batch"). (nullable) - `autoApplyUpdates` (boolean): Whether to automatically apply card updates. (nullable) - `autoApplyExpirationOnly` (boolean): If true, only auto-apply expiration changes; hold PAN changes for review. (nullable) - `notificationEnabled` (boolean): Whether email notifications are enabled. (nullable) - `notificationEmailAddresses` (array): Notification email addresses. (nullable) - `maxBatchSize` (integer(int32)): Maximum cards per batch. (nullable) - `providerFieldValues` (array<[AccountUpdaterFieldValueDto](https://devportal.demo.winkpg.io/docs/api/models/AccountUpdaterFieldValueDto.md)>): Provider-specific configuration field values. (nullable) - `merchantFlowConfig` ([MerchantFlowConfig](https://devportal.demo.winkpg.io/docs/api/models/MerchantFlowConfig.md)): Gets or sets the optional transaction flow configuration that controls how transactions are orchestrated for this merchant. Fields: - `id` (string(uuid)): Identifier of the flow configuration. Assigned by the platform. (nullable) - `name` (string): Display name of the flow configuration. Optional and not used for matching. (nullable) - `screening` ([FraudScreeningConfig](https://devportal.demo.winkpg.io/docs/api/models/FraudScreeningConfig.md)): Transaction screening configuration for this merchant. Null or absent leaves every screening rule unconfigured, which screens nothing. - `billingAssignment` ([MerchantBillingAssignment](https://devportal.demo.winkpg.io/docs/api/models/MerchantBillingAssignment.md)): 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. Fields: - `pricePlanId` (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) - `effectiveFrom` (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) - `effectiveTo` (string(date-time)): Optional end date for the assignment. Billing runs after this date will skip the merchant. Null means open-ended. (nullable) - `fulfillmentPath` ([BillingFulfillmentPath](https://devportal.demo.winkpg.io/docs/api/models/BillingFulfillmentPath.md)): 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: - `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. - `notes` (array<[EntityNote](https://devportal.demo.winkpg.io/docs/api/models/EntityNote.md)>): Gets or sets operational notes attached to the merchant. (nullable) Fields of each item: - `id` (string(uuid)) - `enteredBy` (string(uuid)) - `timestamp` (string(date-time)) - `enteredByName` (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) - `content` (string): (nullable, min length 0, max length 1000) - `saveWarnings` (array<[MerchantSaveWarning](https://devportal.demo.winkpg.io/docs/api/models/MerchantSaveWarning.md)>): 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) Fields of each item: - `code` (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) - `propertyName` (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) - `message` (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) - `groupRationale` (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) - `volumeTrend` (array): 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) - `digitalWallets` (array<[MerchantDigitalWallet](https://devportal.demo.winkpg.io/docs/api/models/MerchantDigitalWallet.md)>): 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) Fields of each item: - `walletProviderType` ([WalletProviderType](https://devportal.demo.winkpg.io/docs/api/models/WalletProviderType.md)): Which wallet this entry describes (Apple Pay, Google Pay, …). (nullable) Values: - `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` (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) - `paymentTokenizationRegistrationId` (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) - `threeDSBindings` (array<[MerchantThreeDSBinding](https://devportal.demo.winkpg.io/docs/api/models/MerchantThreeDSBinding.md)>): 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. The JWT secret is never populated on a read. 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) Fields of each item: - `providerType` ([ThreeDSProviderType](https://devportal.demo.winkpg.io/docs/api/models/ThreeDSProviderType.md)): 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: - `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` (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) - `policyMode` ([ThreeDSPolicyMode](https://devportal.demo.winkpg.io/docs/api/models/ThreeDSPolicyMode.md)): How hard the merchant wants authentication applied. Null means the platform default, which callers read as `Off`. (nullable) Values: - `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` (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. (nullable, max length 256) - `jwtSecret` (string): The shared secret the request JWT is signed with. Stored encrypted. 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. (nullable, max length 512) - `jwtSecretConfigured` (boolean): Whether a JWT secret is stored for this binding, for the editor that is never allowed to see the secret itself. (nullable) - `endpointEnvironment` ([ThreeDSEndpointEnvironment](https://devportal.demo.winkpg.io/docs/api/models/ThreeDSEndpointEnvironment.md)): Which of the vendor's environments this binding points at. Null reads as `Sandbox`. (nullable) Values: - `Sandbox`: The vendor's test environment. The safe landing spot for an absent stored value. - `Live`: The vendor's production environment. - `requestorUrl` (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. (nullable, max length 512) - `challengeEnabled` (boolean): Whether the merchant permits the vendor to raise an interactive challenge. Null reads as not enabled. (nullable) - `protocolVersion` (string): The 3-D Secure protocol version to request, from `SupportedProtocolVersions`. Null means the provider's own default. Conditional: When ProtocolVersion is not empty. (nullable, max length 16) - `providerRegistrationId` (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) - `taxBindings` (array<[MerchantTaxBinding](https://devportal.demo.winkpg.io/docs/api/models/MerchantTaxBinding.md)>): 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. Secret field values are never populated on a read. 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) Fields of each item: - `providerName` (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. (nullable, max length 64) - `isEnabled` (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) - `credentialSource` ([TaxCredentialSource](https://devportal.demo.winkpg.io/docs/api/models/TaxCredentialSource.md)): Whose provider account the lookups are billed to. Null reads as `Gateway`. (nullable) Values: - `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` (array<[TaxBindingFieldValue](https://devportal.demo.winkpg.io/docs/api/models/TaxBindingFieldValue.md)>): The provider-declared configuration values for this merchant, keyed by the setting names the provider declares. Secret values are stored encrypted 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) - `defaultCountryCode` (string): The country code to use for a lookup that does not name one. Null falls back to the gateway-wide `TaxCalculation.DefaultCountryCode` setting. (nullable, max length 3) - `shippingBindings` (array<[MerchantShippingBinding](https://devportal.demo.winkpg.io/docs/api/models/MerchantShippingBinding.md)>): 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. Secret field values are never populated on a read. 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) Fields of each item: - `providerName` (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. (nullable, max length 64) - `isEnabled` (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) - `credentialSource` ([ProviderCredentialSource](https://devportal.demo.winkpg.io/docs/api/models/ProviderCredentialSource.md)): Whose provider account the quotes are billed to. Null reads as `Gateway`. (nullable) Values: - `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` (array<[ShippingBindingFieldValue](https://devportal.demo.winkpg.io/docs/api/models/ShippingBindingFieldValue.md)>): 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. Secret values are stored encrypted 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) - `paymentEncryptionBindings` (array<[MerchantPaymentEncryptionBinding](https://devportal.demo.winkpg.io/docs/api/models/MerchantPaymentEncryptionBinding.md)>): 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. Secret field values and key references are never populated on a read. 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) Fields of each item: - `providerName` (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. (nullable, max length 64) - `isEnabled` (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) - `credentialSource` ([PaymentEncryptionCredentialSource](https://devportal.demo.winkpg.io/docs/api/models/PaymentEncryptionCredentialSource.md)): Whose provider account the decryption calls are billed to. Null reads as `Gateway`. (nullable) Values: - `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` (array<[PaymentEncryptionBindingFieldValue](https://devportal.demo.winkpg.io/docs/api/models/PaymentEncryptionBindingFieldValue.md)>): The provider-declared configuration values for this merchant, keyed by the setting names the provider declares. Secret values are stored encrypted 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) - `keyEntries` (array<[PaymentEncryptionKeyEntry](https://devportal.demo.winkpg.io/docs/api/models/PaymentEncryptionKeyEntry.md)>): The key serial identifier entries that map an inbound key serial number to an HSM key. Conditional: When KeyEntries is not null. (nullable) - `primaryEndpoint` (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. (nullable, max length 512) - `secondaryEndpoint` (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. (nullable, max length 512) - `decryptTimeoutMillisecondsOverride` (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) - `promotedAt` (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) - `promotedByUserId` (string(uuid)): The user who ran the promotion that stamped `promotedAt`, or null when the merchant has never been promoted through that action. (nullable) - `isLocked` (boolean): (nullable) - `lockedAt` (string(date-time)): (nullable) - `lockedByUserId` (string(uuid)): (nullable) - `lockedByUserName` (string): (nullable) - `lockReason` (string): (nullable) _Example: Active merchant_ An active production merchant under its reseller, with its contact details and the currency it processes in. ```json { "id": "00000000-0000-0000-0000-000000000001", "name": "Sample Merchant", "concurrencyStamp": "3f9a1c7e5b2d4e8f9a0b1c2d3e4f5a6b", "resellerId": "5c2e7a90-1b3d-4e6f-8a0b-1c2d3e4f5a01", "resellerName": "Sample Reseller", "entityVersion": 0, "customIdentifier": "SM-0001", "dba": "Sample Outdoor Supply", "mcc": "5999", "isTest": false, "environment": "Production", "isActive": true, "contactDetail": { "primaryContactName": "Jane Smith", "emailAddress": "jane.smith@example.com", "phone": "555-555-0100", "fax": "", "companyUrl": "https://www.example.com", "addresses": [ { "id": "3b8d0f25-7c4e-4a69-8b1d-2e3f4a5b6c01", "address1": "100 Main St", "address2": "", "city": "Phoenix", "state": "AZ", "province": "", "zip": "85004", "postalCode": "", "country": "USA", "isMailing": true, "isDefault": true } ] }, "businessInfo": { "currency": "USD" }, "virtualTerminal": { "cardBinPrompting": { "enableCommercial": false, "enableGsa": false, "enableFsa": false }, "allowRepeatSales": false, "allowRefunds": false, "enableEmailReceipts": true, "fields": { "customer": { "allowAddNew": false, "fieldKey": "Customer", "enabled": false, "required": false }, "invoiceNumber": { "fieldKey": "InvoiceNum", "enabled": false, "required": false }, "purchaseOrderNumber": { "fieldKey": "PONum", "enabled": false, "required": false }, "billingAddress": { "requireOnlyAvsFields": false, "fieldKey": "BillingAddress", "enabled": false, "required": false }, "shippingAddress": { "defaultToSameAsBilling": true, "fieldKey": "ShippingAddress", "enabled": false, "required": false }, "contactPhone": { "maskField": true, "maskExpression": "(000) 000-0000", "fieldKey": "Phone", "enabled": false, "required": false }, "level3Amount": { "fieldKey": "Level3Amount", "enabled": false, "required": false }, "shippingAmount": { "fieldKey": "ShippingAmount", "enabled": false, "required": false }, "convenienceAmount": { "autoCalculate": false, "customName": "Convenience Fee", "readOnly": false, "fieldKey": "ConvenienceFee", "enabled": false, "required": false }, "dutyAmount": { "fieldKey": "DutyAmount", "enabled": false, "required": false }, "tipAmount": { "fieldKey": "TipAmount", "enabled": false, "required": false }, "taxAmount": { "autoCalculate": false, "fieldKey": "TaxAmount", "enabled": false, "required": false }, "emailAddress": { "validateFormat": false, "validationRegex": "^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$", "placeholder": "Email Address", "fieldKey": "Email", "enabled": false, "required": false } }, "allowPartialApprovals": true, "allowSplitTender": true, "allowTipAdjustmentOnPartialApproval": false, "splitTenderMaxTenders": 2, "partialApprovalAckTimeoutMinutes": 15 }, "processing": { "duplicateCheck": { "enable": true, "includeInvoiceNumber": false, "allowOverride": true }, "orderDataDefaults": { "enable": false, "applyLevel2DefaultsToApi": true, "applyLevel3DefaultsToApi": true, "applyLevel2DefaultsToVt": true, "applyLevel3DefaultsToVt": true }, "cardVerification": { "avNoMatch": true, "avPartialMatch": true, "avPartialMatchIntl": false, "avNoMatchIntl": false, "avMatchIntl": false, "avError": true, "avMatchUK": false, "avNotSupportedIntl": false, "avIntlNoMatch": false, "avMatchIntlBoth": false, "avZipMatchIntl": false, "avRetry": true, "avNotSupported": true, "avUnavailable": true, "avZipPartialMatch9Digit": true, "avZipMatch9Digit": true, "avZipMatch5Digit": true, "avZipPartialMatch5Digit": true, "cvvMatch": true, "cvvNoMatch": true, "cvvNotProcessed": true, "cvvNotProvided": true, "cvvIssuerNotCertified": true, "cvvUnableToProcess": true }, "requireLevel2Data": false, "requireNameOnCard": false, "requireZipCode": false, "requireShipping": false, "enableForceCapture": false, "processorProfiles": [ ], "autoSettlement": { "enable": false, "sendMerchantEmail": false, "userNotificationType": "Primary", "additionalEmailNotifications": [ ], "currentBatchIds": { } }, "registers": [ ] }, "features": { "enableGsaBinCheck": false, "enableAuthEdit": false, "configurationLimits": { "allowCustomFieldConfig": true, "allowHostedPaymentPageConfig": false, "allowOrderDataDefaultsConfig": false, "allowEmulatorConfig": false, "allowFraudControlConfig": false, "allowFraudLog": false, "allowQuickPayConfig": false, "allowPaymentTokenizationConfig": false }, "merchantBilling": { } }, "capabilities": { "alternateCardTenders": { "ebtSnap": false, "ebtCash": false, "ewic": false, "any": false } }, "customFields": [ ], "notes": [ ], "digitalWallets": [ ], "threeDSBindings": [ ], "taxBindings": [ ], "shippingBindings": [ ], "paymentEncryptionBindings": [ ], "isDeleted": false, "lastModificationTime": "2026-01-10T17:30:00.0000000+00:00", "creationTime": "2025-06-01T16:00:00.0000000+00:00", "extraProperties": { } } ``` ### 403 Forbidden **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) ### 401 Unauthorized **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) ### 400 Bad Request **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) _Example: Request failed validation_ One or more fields were rejected before any rule ran. error.code is null on the envelope and the causes are in validationErrors, one entry per failure. An entry carries code when the validator declared a publishable one, and memberPaths when the full path says more than members does (an element inside a collection, for example). Both keys are omitted when they would add nothing. ```json { "error": { "code": "null", "message": "Your request is not valid!", "details": "The following errors were detected during validation.", "data": { "correlationId": "0123456789abcdef0123456789abcdef" }, "validationErrors": [ { "message": "'Amount' must be greater than 0.", "members": [ "amount" ] }, { "message": "The card has expired.", "members": [ "expirationDate" ], "code": "CardData:CardExpired" }, { "message": "'Value' must not be empty.", "members": [ "value" ], "memberPaths": [ "customFields[2].value" ] } ] } } ``` ### 404 Not Found **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) _Example: Resource not found_ The id in the path names no record the caller can see. Most resources answer with a null error.code and a message naming the resource type and the id; a resource that publishes a not-found code in the catalog above carries it in error.code instead, so check for one before matching on the message. ```json { "error": { "code": "null", "message": "There is no entity Transaction with id = 7d1f3a52-0c4e-4b8a-9e21-5a6b7c8d9e00!", "details": "null", "data": { "correlationId": "0123456789abcdef0123456789abcdef" }, "validationErrors": "null" } } ``` ### 501 Not Implemented **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) ### 500 Internal Server Error **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) ### default The request failed. The body carries the standard error envelope: a machine-readable `error.code`, a human-readable `error.message`, and `error.validationErrors` when the failure was a validation rejection. The [error reference](https://devportal.demo.winkpg.io/docs/errors.md) lists the values `error.code` can take. **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) _Example: Business rule refused the request_ The request was understood and rejected by a platform rule. This is the shape that carries a code from the catalog above, so branch on error.code rather than on the message text. The HTTP status is the one listed against the code. ```json { "error": { "code": "Transactions:OperationNotAllowed", "message": "The operation 'Void' is not allowed on a Sale transaction with result 'Approved' and settlement state 'Settled'.", "details": "null", "data": { "correlationId": "0123456789abcdef0123456789abcdef" }, "validationErrors": "null" } } ``` ### 429 The request was refused because a rate limit was exceeded, or because something a later retry can clear stopped it. A rate limit refusal carries an `application/problem+json` body: wait at least the interval `Retry-After` names before retrying, then back off. Limits are tuned per deployment, so read the allowance from the response headers rather than assuming a fixed ceiling. Any other refusal carries the standard error envelope as `application/json`, and its `error.code` names the cause. **Content type:** `application/problem+json` Schema: [`RateLimitProblemDetails`](https://devportal.demo.winkpg.io/docs/api/models/RateLimitProblemDetails.md) Properties: - `type` (string) required: The problem type identifier. Always the same value: the failure is the status code itself, so there is no sub-type for a caller to branch on. (nullable) - `title` (string) required: A short, human-readable summary of the problem type. (nullable) - `status` (integer(int32)) required: The HTTP status code, repeated in the body as the problem-details format defines. - `detail` (string) required: A human-readable explanation of this occurrence of the problem. (nullable) - `retryAfterSeconds` (integer(int32)) required: How long to wait before retrying, in whole seconds, carrying the same figure as the `Retry-After` header. Always at least one: a value of zero would invite an immediate retry that is certain to be rejected again. **Content type:** `application/json` Schema: [`RemoteServiceErrorResponse`](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorResponse.md) Properties: - `error` ([RemoteServiceErrorInfo](https://devportal.demo.winkpg.io/docs/api/models/RemoteServiceErrorInfo.md)) ## 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. ### cURL ```bash curl -X POST "{{BASE_URL}}/api/merchants/{id}/unlock" \ -H "api-key: {{API_KEY}}" ``` ### PowerShell ```powershell $headers = @{ 'api-key' = '{{API_KEY}}' } $response = Invoke-RestMethod -Method POST -Uri '{{BASE_URL}}/api/merchants/{id}/unlock' ` -Headers $headers ``` ### TypeScript (SDK) ```bash npm install @winkpg/winkpg-api ``` ```typescript import { Configuration, MerchantsApi } from '@winkpg/winkpg-api'; const api = new MerchantsApi(new Configuration({ basePath: '{{BASE_URL}}', apiKey: '{{API_KEY}}', })); const { data } = await api.merchantsUnlock("3fa85f64-5717-4562-b3fc-2c963f66afa6"); ``` ### TypeScript (raw HTTP) ```typescript const response = await fetch('{{BASE_URL}}/api/merchants/{id}/unlock', { method: 'POST', headers: { "api-key": "{{API_KEY}}", }, }); const data = await response.json(); ``` ### C# (SDK) ```bash dotnet add package WinkPg.Api.Client ``` ```csharp using WinkPg.Api.Client.Api; using WinkPg.Api.Client.Client; var config = new Configuration { BasePath = "{{BASE_URL}}" }; config.AddApiKey("api-key", "{{API_KEY}}"); var api = new MerchantsApi(config); var result = await api.MerchantsUnlockAsync(Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6")); ``` ### C# (raw HTTP) ```csharp using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") }; var request = new HttpRequestMessage(new HttpMethod("POST"), "/api/merchants/{id}/unlock"); request.Headers.Add("api-key", "{{API_KEY}}"); var response = await http.SendAsync(request); response.EnsureSuccessStatusCode(); var json = await response.Content.ReadAsStringAsync(); ``` ### Python (SDK) ```bash pip install winkpg-api ``` ```python import winkpg_api configuration = winkpg_api.Configuration(host="{{BASE_URL}}") configuration.api_key["ApiKey"] = "{{API_KEY}}" with winkpg_api.ApiClient(configuration) as client: api = winkpg_api.MerchantsApi(client) result = api.merchants_unlock("3fa85f64-5717-4562-b3fc-2c963f66afa6") ``` ### Python (raw HTTP) ```bash pip install requests ``` ```python import requests headers = { "api-key": "{{API_KEY}}", } response = requests.request( "POST", "{{BASE_URL}}/api/merchants/{id}/unlock", headers=headers, ) response.raise_for_status() data = response.json() ``` ## See also - [All documentation](https://devportal.demo.winkpg.io/llms.txt): the machine-readable index of every public page on this site.