Stored Credential Consents: Gets the consent text to show the cardholder.

Example request

Each example below is one request, shown in every language. Choose an example and a language, then replace {{BASE_URL}} with the address of the API you are calling and {{API_KEY}} with your own key.

The request body is a GetConsentConfigInput. See the Request body section below for its fields.

cURL PowerShell TypeScript C# Python

Card saved for recurring payments

Gets the text to show a cardholder who is saving a card for a subscription. Show the returned text next to the consent checkbox, then send the returned version as consentTextVersion when you store the card. Omit merchantName to use your merchant's display name.

cURL

curl -X POST "{{BASE_URL}}/api/stored-credential-consents/consent-config" \
  -H "api-key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
  "usage": "Recurring",
  "merchantName": "Acme Fitness",
  "kind": "Card"
}'

PowerShell

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

$body = @'
{
  "usage": "Recurring",
  "merchantName": "Acme Fitness",
  "kind": "Card"
}
'@

$response = Invoke-RestMethod -Method POST -Uri '{{BASE_URL}}/api/stored-credential-consents/consent-config' `
    -Headers $headers -ContentType 'application/json' -Body $body

npm install @winkpg/winkpg-api

TypeScript (SDK)

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

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

const { data } = await api.consentConfigGet({
  "usage": "Recurring",
  "merchantName": "Acme Fitness",
  "kind": "Card"
});

TypeScript (raw HTTP)

const response = await fetch('{{BASE_URL}}/api/stored-credential-consents/consent-config', {
  method: 'POST',
  headers: {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "usage": "Recurring",
    "merchantName": "Acme Fitness",
    "kind": "Card"
  }),
});

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 StoredCredentialConsentsApi(config);
var body = JsonSerializer.Deserialize<GetConsentConfigInput>("""
    {
      "usage": "Recurring",
      "merchantName": "Acme Fitness",
      "kind": "Card"
    }
    """);

var result = await api.ConsentConfigGetAsync(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/stored-credential-consents/consent-config");
request.Headers.Add("api-key", "{{API_KEY}}");

request.Content = new StringContent("""
    {
      "usage": "Recurring",
      "merchantName": "Acme Fitness",
      "kind": "Card"
    }
    """, 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.StoredCredentialConsentsApi(client)
    body = winkpg_api.GetConsentConfigInput.from_dict({
      "usage": "Recurring",
      "merchantName": "Acme Fitness",
      "kind": "Card"
    })
    result = api.consent_config_get(body)

pip install requests

Python (raw HTTP)

import requests

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

body = {
  "usage": "Recurring",
  "merchantName": "Acme Fitness",
  "kind": "Card"
}

response = requests.request(
    "POST",
    "{{BASE_URL}}/api/stored-credential-consents/consent-config",
    headers=headers,
    json=body,
)
response.raise_for_status()
data = response.json()

Card saved for recurring payments with a convenience fee

Gets the subscription consent text with the convenience fee every charge carries, so the cardholder agrees to the fee before the first charge. Pass only a fee your charges actually assess.

cURL

curl -X POST "{{BASE_URL}}/api/stored-credential-consents/consent-config" \
  -H "api-key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
  "usage": "Recurring",
  "kind": "Card",
  "convenienceFeeDisclosure": "$2.50 per payment"
}'

PowerShell

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

$body = @'
{
  "usage": "Recurring",
  "kind": "Card",
  "convenienceFeeDisclosure": "$2.50 per payment"
}
'@

$response = Invoke-RestMethod -Method POST -Uri '{{BASE_URL}}/api/stored-credential-consents/consent-config' `
    -Headers $headers -ContentType 'application/json' -Body $body

npm install @winkpg/winkpg-api

TypeScript (SDK)

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

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

const { data } = await api.consentConfigGet({
  "usage": "Recurring",
  "kind": "Card",
  "convenienceFeeDisclosure": "$2.50 per payment"
});

TypeScript (raw HTTP)

const response = await fetch('{{BASE_URL}}/api/stored-credential-consents/consent-config', {
  method: 'POST',
  headers: {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "usage": "Recurring",
    "kind": "Card",
    "convenienceFeeDisclosure": "$2.50 per payment"
  }),
});

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 StoredCredentialConsentsApi(config);
var body = JsonSerializer.Deserialize<GetConsentConfigInput>("""
    {
      "usage": "Recurring",
      "kind": "Card",
      "convenienceFeeDisclosure": "$2.50 per payment"
    }
    """);

var result = await api.ConsentConfigGetAsync(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/stored-credential-consents/consent-config");
request.Headers.Add("api-key", "{{API_KEY}}");

request.Content = new StringContent("""
    {
      "usage": "Recurring",
      "kind": "Card",
      "convenienceFeeDisclosure": "$2.50 per payment"
    }
    """, 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.StoredCredentialConsentsApi(client)
    body = winkpg_api.GetConsentConfigInput.from_dict({
      "usage": "Recurring",
      "kind": "Card",
      "convenienceFeeDisclosure": "$2.50 per payment"
    })
    result = api.consent_config_get(body)

pip install requests

Python (raw HTTP)

import requests

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

body = {
  "usage": "Recurring",
  "kind": "Card",
  "convenienceFeeDisclosure": "$2.50 per payment"
}

response = requests.request(
    "POST",
    "{{BASE_URL}}/api/stored-credential-consents/consent-config",
    headers=headers,
    json=body,
)
response.raise_for_status()
data = response.json()

Bank account saved for future payments

Gets the bank account authorization text for a customer saving a bank account to pay later invoices on request.

cURL

curl -X POST "{{BASE_URL}}/api/stored-credential-consents/consent-config" \
  -H "api-key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
  "usage": "UnscheduledCOF",
  "kind": "Ach"
}'

PowerShell

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

$body = @'
{
  "usage": "UnscheduledCOF",
  "kind": "Ach"
}
'@

$response = Invoke-RestMethod -Method POST -Uri '{{BASE_URL}}/api/stored-credential-consents/consent-config' `
    -Headers $headers -ContentType 'application/json' -Body $body

npm install @winkpg/winkpg-api

TypeScript (SDK)

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

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

const { data } = await api.consentConfigGet({
  "usage": "UnscheduledCOF",
  "kind": "Ach"
});

TypeScript (raw HTTP)

const response = await fetch('{{BASE_URL}}/api/stored-credential-consents/consent-config', {
  method: 'POST',
  headers: {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "usage": "UnscheduledCOF",
    "kind": "Ach"
  }),
});

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 StoredCredentialConsentsApi(config);
var body = JsonSerializer.Deserialize<GetConsentConfigInput>("""
    {
      "usage": "UnscheduledCOF",
      "kind": "Ach"
    }
    """);

var result = await api.ConsentConfigGetAsync(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/stored-credential-consents/consent-config");
request.Headers.Add("api-key", "{{API_KEY}}");

request.Content = new StringContent("""
    {
      "usage": "UnscheduledCOF",
      "kind": "Ach"
    }
    """, 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.StoredCredentialConsentsApi(client)
    body = winkpg_api.GetConsentConfigInput.from_dict({
      "usage": "UnscheduledCOF",
      "kind": "Ach"
    })
    result = api.consent_config_get(body)

pip install requests

Python (raw HTTP)

import requests

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

body = {
  "usage": "UnscheduledCOF",
  "kind": "Ach"
}

response = requests.request(
    "POST",
    "{{BASE_URL}}/api/stored-credential-consents/consent-config",
    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.

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

usage required

StoredCredentialUsage StoredCredentialUsage

Filter for which `StoredCredentialUsage` scopes to render bullets for. When null or `None`, all permitted scopes render; the caller is expected to be rendering a generic consent page. 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

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.

`None`	No permitted uses. Consent record is effectively inactive.
`Recurring`	Scheduled recurring charges (subscriptions, membership dues). Maps to Recurring.
`Installment`	Fixed-schedule installment plans dividing a known total. Maps to Installment.
`UnscheduledCOF`	Merchant-triggered charges for pre-agreed events (balance top-ups, usage overages, no-show fees, delayed charges). Maps to several MIT reason codes including UnscheduledCOF, NoShow, DelayedCharge, and IncrementalAuth.
`OneTimeFuture`	A single known future cardholder-initiated purchase the credential was saved for (e.g. "save card for my next order"). Not used for MITs.

merchantName required

string

Merchant name to substitute into `{{MerchantName}}`. Optional. When unset, the service falls back to the authenticated merchant's display name. Conditional: When MerchantName is not null. Max length: 200. 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.

kind required

ConsentPaymentKind ConsentPaymentKind

Which payment instrument the consent applies to. Selects the card vs ACH sibling template and the matching tokenization-protection wording. Defaults to `Card`.

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.

`Card`	Card credentials. Renders ConsentTemplateNames.Consent (the default).
`Ach`	Bank account (ACH). Renders ConsentTemplateNames.AchConsent.

convenienceFeeDisclosure required

string

Free-text description of a convenience fee the cardholder will be charged on every charge under this authorization (e.g. "$2.50 per payment"). Substituted into Section 3 of the rendered text; when null or blank, the fee line does not render at all. Conditional: When ConvenienceFeeDisclosure is not null. Max length: 500. 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.

cardPriceDisclosure required

string

Free-text statement of the card price charged to a card on every charge under this authorization, for a merchant that posts a cash price and a card price (e.g. "$104.00 per payment, against a cash price of $100.00"). Substituted into Section 3 of the rendered text; when null or blank, the card price line does not render at all. Card consents only. Conditional: When CardPriceDisclosure is not null. Max length: 500. 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.

surchargeDisclosure required

string

Statement of the surcharge ceiling a recurring or installment charge to a card may carry (e.g. "up to 3 percent of each payment, added to the amount above when a credit card is charged"). Substituted into Section 3 of the rendered text; when null or blank, the surcharge line does not render at all. Card consents only. Conditional: When SurchargeDisclosure is not null. Max length: 500. 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 request body has no documented fields.

Responses

200 OK

The consent text and its version.

Body: ConsentConfigDto ConsentConfigDto Each item has these fields.

Field Type Description

isConsentRequired required

boolean

True when the authenticated merchant's scope has consent capture enforced. A transaction that tokenizes/persists a card without a `StoredCredentialConsentInput` will be rejected with `stored_credential_consent_required`.

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.

allowedUsages required

StoredCredentialUsage StoredCredentialUsage

The usage scopes the merchant's configuration permits. Matches the flags that can legitimately appear on captured consents for this merchant; consumers render only the matching checkboxes / bullets. 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.

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.

`None`	No permitted uses. Consent record is effectively inactive.
`Recurring`	Scheduled recurring charges (subscriptions, membership dues). Maps to Recurring.
`Installment`	Fixed-schedule installment plans dividing a known total. Maps to Installment.
`UnscheduledCOF`	Merchant-triggered charges for pre-agreed events (balance top-ups, usage overages, no-show fees, delayed charges). Maps to several MIT reason codes including UnscheduledCOF, NoShow, DelayedCharge, and IncrementalAuth.
`OneTimeFuture`	A single known future cardholder-initiated purchase the credential was saved for (e.g. "save card for my next order"). Not used for MITs.

text required

ConsentTextConfigDto ConsentTextConfigDto

Rendered consent text with version metadata.

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 ConsentTextConfigDto:

Field Type Description

version required

string

Version hash of the rendered template. Clients persist this and submit it back on the transaction so WinkPG records exactly what the cardholder saw. 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.

rendered required

string

Fully-rendered, substituted consent text with merchant variables applied. No `{{Variable}}` markers should remain in well-configured merchants; any that do are surfaced via `missingVariables` for diagnosis. 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.

locale required

string

Locale of the rendered text. Single-locale (en-US) for v1. 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.

lastUpdatedAt required

string (date-time)

Reserved. Always `1970-01-01T00:00:00Z` today; `version` is the identity of the text.

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.

missingVariables required

array of string array of

Reserved for the names of template variables that had no value at render time. Always empty today. 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.

disclosures required

ConsentDisclosuresDto ConsentDisclosuresDto

Merchant-configured disclosure URLs referenced from the consent text.

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 ConsentDisclosuresDto:

Field Type Description

termsUrl required

string

Merchant's terms of service URL. Empty when not configured. 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.

privacyUrl required

string

Merchant's privacy policy URL. Empty when not configured. 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.

This response has no documented body fields.

429 Too Many Requests

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 400 401 403 404 500 501 default

400 Bad Request Bad request. The request was malformed or failed validation. When validation rejected it, `error.validationErrors` names each member at fault and why.
401 Unauthorized Unauthorized. The request carried no API key or signed-in session, or the key it carried is invalid, revoked or expired.
403 Forbidden Forbidden. The API key lacks the scope this operation needs, the signed-in user lacks the permission, or a business rule refused the request. The error code in the body names the reason.
404 Not Found Not found. The resource the request names does not exist or is not visible to the caller: a resource that belongs to a merchant or tenant outside the caller's scope is reported as not found.
500 Internal Server Error Internal server error. The platform failed unexpectedly while handling the request. If it keeps failing, contact support and quote the correlation id, which the response carries in the `X-Correlation-Id` header and as `error.data.correlationId`.
501 Not Implemented Not implemented. The operation is declared but has no implementation on this deployment, so no request to it can succeed. Retrying does not help.
default The request failed. The body carries the standard error envelope: a machine-readable `error.code`, a human-readable `error.message`, and `error.validationErrors` when the failure was a validation rejection. The error reference 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.

Fields of RemoteServiceErrorInfo:

Field Type Description

code 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.

message 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.

details 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.

data required

object

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.

validationErrors required

array of RemoteServiceValidationErrorInfo array of RemoteServiceValidationErrorInfo

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.

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 Stored Credential Consents

Authentication

ApiKey with scopes

The API reference isn't available right now

No such operation

This reference may be out of date

Stored Credential Consents: Gets the consent text to show the cardholder.

Example request

Parameters

Request body

Responses

Errors

Authentication