Surcharging: Creates a merchant's initial surcharge configuration.

POST /api/surcharging/configurations deprecated

Requires: Surcharging.Configuration.Manage, merchant scope.

**Required permissions**: `Surcharging.Configuration.Manage` **Scope**: merchant

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

cURL PowerShell TypeScript C# Python

cURL

curl -X POST "{{BASE_URL}}/api/surcharging/configurations" \
  -H "api-key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'

PowerShell

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

$body = @'
{
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
'@

$response = Invoke-RestMethod -Method POST -Uri '{{BASE_URL}}/api/surcharging/configurations' `
    -Headers $headers -ContentType 'application/json' -Body $body

npm install @winkpg/winkpg-api

TypeScript (SDK)

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

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

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

TypeScript (raw HTTP)

const response = await fetch('{{BASE_URL}}/api/surcharging/configurations', {
  method: 'POST',
  headers: {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }),
});

const data = await response.json();

dotnet add package WinkPg.Api.Client

C# (SDK)

using WinkPg.Api.Client.Api;
using WinkPg.Api.Client.Client;
using System.Text.Json;

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

var api = new SurchargingApi(config);
var body = JsonSerializer.Deserialize<CreateSurchargeConfigurationDto>("""
    {
      "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
    """);

var result = await api.SurchargeConfigurationCreateAsync(body);

C# (raw HTTP)

using System.Text;

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

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

request.Content = new StringContent("""
    {
      "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
    """, Encoding.UTF8, "application/json");

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

pip install winkpg-api

Python (SDK)

import winkpg_api

configuration = winkpg_api.Configuration(host="{{BASE_URL}}")
configuration.api_key["ApiKey"] = "{{API_KEY}}"

with winkpg_api.ApiClient(configuration) as client:
    api = winkpg_api.SurchargingApi(client)
    body = winkpg_api.CreateSurchargeConfigurationDto.from_dict({
      "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    })
    result = api.surcharge_configuration_create(body)

pip install requests

Python (raw HTTP)

import requests

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

body = {
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

response = requests.request(
    "POST",
    "{{BASE_URL}}/api/surcharging/configurations",
    headers=headers,
    json=body,
)
response.raise_for_status()
data = response.json()

Parameters

Name	In	Type	Description
`suppressNulls` required	query	boolean	If true, omit properties with null values.

Request body

application/json , required

Field	Type	Description
`defaultRate` required	number (double)	Default surcharge rate (decimal fraction, 0.03 = 3%) when no network override applies. Conditional: When DefaultRate is not null. Range: 0 to 0.03. Conditional: When DefaultRate is not null and AttestedCostOfAcceptanceRate is not null. Must be <= . nullable
`attestedCostOfAcceptanceRate` required	number (double)	The merchant's attested effective cost of acceptance (decimal fraction, 0.024 = 2.4%), sourced from their statement analysis. A surcharge may never exceed this, so a configured rate above it (or above the 3% network cap) is rejected at save. Supplying a value records the attestation with the acting user and a timestamp; null leaves it unattested and withdraws any prior attestation. Conditional: When AttestedCostOfAcceptanceRate is not null. Range: 0 to 1. nullable
`channelRestrictions` required	all of SurchargeChannelFlags	A combination of channel flags. Send member names separated by a comma and a space (for example "Api, HostedPaymentPage") or the integer sum (VirtualTerminal = 1, Api = 2, HostedPaymentPage = 4, RecurringBilling = 8). None (0) turns surcharging off on every channel. Replaced on update; null or omitted stores no channels. Conditional: When ChannelRestrictions is not null. 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. nullable
`networkPolicies` required	array of SurchargeNetworkPolicyDto	Per-network surcharge policies. Replaces the stored set in full on update. Conditional: When NetworkPolicies is not null. nullable
`differentialNetworkRatesAttested` required	boolean	Attests that differing surcharge rates across the allowed card networks carry documented legal signoff. Must be true whenever `networkPolicies` resolves to more than one distinct rate across the allowed networks; ignored otherwise. Card-brand non-discrimination and parity provisions are what make the signoff necessary. nullable
`disclosureCopyTemplate` required	string	The merchant's own surcharge disclosure copy, written in the token grammar defined by `SurchargeDisclosureCopy`: it must carry `{rate}` and `{costOfAcceptance}`, may carry `{amount}`, and may carry no other brace-delimited placeholder. Null or blank leaves every surface on its platform default copy. Conditional: When IsConfigured(DisclosureCopyTemplate) is true. nullablemax length 1000
`merchantId` required	string (uuid)	The merchant to create the configuration for.
`holdPromotion` required	boolean	Whether to place an explicit promotion hold on the configuration as it is created, so it can never be promoted out of the waiting period until the hold is released. nullable
`promotionHoldReason` required	string	Why the promotion is being withheld, recorded when `holdPromotion` is set. Ignored when it is not. nullablemax length 500

This request body has no documented fields.