Adds a new stored payment method to a customer's collection and persists it.

POST /api/customers/add-stored-payment-method-async deprecated

Requires: Customers.Customers, Customers.Customers.Create, merchant scope.

**Required permissions**: `Customers`, `Customers.Create` **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 AddStoredPaymentMethodInput. See the Request body section below for its fields.

cURL PowerShell TypeScript C# Python

cURL

curl -X POST "{{BASE_URL}}/api/customers/add-stored-payment-method-async" \
  -H "api-key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
  "paymentMethodType": "Card",
  "cardData": {
    "cardNumber": "4111111111111111",
    "expirationDate": "2028-10-01",
    "cvv": 123,
    "nameOnCard": "Jane Smith",
    "entryMode": "Manual",
    "cvPresence": "None",
    "billingAddress": {
      "address1": "456 Oak Ave",
      "city": "Reno",
      "state": "NV",
      "zip": "89501",
      "country": "USA"
    }
  },
  "isDefault": true,
  "customName": "Personal Visa"
}'

PowerShell

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

$body = @'
{
  "paymentMethodType": "Card",
  "cardData": {
    "cardNumber": "4111111111111111",
    "expirationDate": "2028-10-01",
    "cvv": 123,
    "nameOnCard": "Jane Smith",
    "entryMode": "Manual",
    "cvPresence": "None",
    "billingAddress": {
      "address1": "456 Oak Ave",
      "city": "Reno",
      "state": "NV",
      "zip": "89501",
      "country": "USA"
    }
  },
  "isDefault": true,
  "customName": "Personal Visa"
}
'@

$response = Invoke-RestMethod -Method POST -Uri '{{BASE_URL}}/api/customers/add-stored-payment-method-async' `
    -Headers $headers -ContentType 'application/json' -Body $body

npm install @winkpg/winkpg-api

TypeScript (SDK)

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

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

const { data } = await api.customersAddStoredPaymentMethod({
  "paymentMethodType": "Card",
  "cardData": {
    "cardNumber": "4111111111111111",
    "expirationDate": "2028-10-01",
    "cvv": 123,
    "nameOnCard": "Jane Smith",
    "entryMode": "Manual",
    "cvPresence": "None",
    "billingAddress": {
      "address1": "456 Oak Ave",
      "city": "Reno",
      "state": "NV",
      "zip": "89501",
      "country": "USA"
    }
  },
  "isDefault": true,
  "customName": "Personal Visa"
});

TypeScript (raw HTTP)

const response = await fetch('{{BASE_URL}}/api/customers/add-stored-payment-method-async', {
  method: 'POST',
  headers: {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "paymentMethodType": "Card",
    "cardData": {
      "cardNumber": "4111111111111111",
      "expirationDate": "2028-10-01",
      "cvv": 123,
      "nameOnCard": "Jane Smith",
      "entryMode": "Manual",
      "cvPresence": "None",
      "billingAddress": {
        "address1": "456 Oak Ave",
        "city": "Reno",
        "state": "NV",
        "zip": "89501",
        "country": "USA"
      }
    },
    "isDefault": true,
    "customName": "Personal Visa"
  }),
});

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 CustomersApi(config);
var body = JsonSerializer.Deserialize<AddStoredPaymentMethodInput>("""
    {
      "paymentMethodType": "Card",
      "cardData": {
        "cardNumber": "4111111111111111",
        "expirationDate": "2028-10-01",
        "cvv": 123,
        "nameOnCard": "Jane Smith",
        "entryMode": "Manual",
        "cvPresence": "None",
        "billingAddress": {
          "address1": "456 Oak Ave",
          "city": "Reno",
          "state": "NV",
          "zip": "89501",
          "country": "USA"
        }
      },
      "isDefault": true,
      "customName": "Personal Visa"
    }
    """);

var result = await api.CustomersAddStoredPaymentMethodAsync(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/customers/add-stored-payment-method-async");
request.Headers.Add("api-key", "{{API_KEY}}");

request.Content = new StringContent("""
    {
      "paymentMethodType": "Card",
      "cardData": {
        "cardNumber": "4111111111111111",
        "expirationDate": "2028-10-01",
        "cvv": 123,
        "nameOnCard": "Jane Smith",
        "entryMode": "Manual",
        "cvPresence": "None",
        "billingAddress": {
          "address1": "456 Oak Ave",
          "city": "Reno",
          "state": "NV",
          "zip": "89501",
          "country": "USA"
        }
      },
      "isDefault": true,
      "customName": "Personal Visa"
    }
    """, 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.CustomersApi(client)
    body = winkpg_api.AddStoredPaymentMethodInput.from_dict({
      "paymentMethodType": "Card",
      "cardData": {
        "cardNumber": "4111111111111111",
        "expirationDate": "2028-10-01",
        "cvv": 123,
        "nameOnCard": "Jane Smith",
        "entryMode": "Manual",
        "cvPresence": "None",
        "billingAddress": {
          "address1": "456 Oak Ave",
          "city": "Reno",
          "state": "NV",
          "zip": "89501",
          "country": "USA"
        }
      },
      "isDefault": True,
      "customName": "Personal Visa"
    })
    result = api.customers_add_stored_payment_method(body)

pip install requests

Python (raw HTTP)

import requests

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

body = {
  "paymentMethodType": "Card",
  "cardData": {
    "cardNumber": "4111111111111111",
    "expirationDate": "2028-10-01",
    "cvv": 123,
    "nameOnCard": "Jane Smith",
    "entryMode": "Manual",
    "cvPresence": "None",
    "billingAddress": {
      "address1": "456 Oak Ave",
      "city": "Reno",
      "state": "NV",
      "zip": "89501",
      "country": "USA"
    }
  },
  "isDefault": True,
  "customName": "Personal Visa"
}

response = requests.request(
    "POST",
    "{{BASE_URL}}/api/customers/add-stored-payment-method-async",
    headers=headers,
    json=body,
)
response.raise_for_status()
data = response.json()

Parameters

Name	In	Type	Description
`customerId` required	query	string (uuid)	The customer to add the payment method to.
`suppressNulls` required	query	boolean	If true, omit properties with null values.

Request body

application/json , required

Field	Type	Description
`paymentMethodType` required	all of CustomerStoredPaymentMethodType	Gets or sets the type of payment method (Card or Check). Conditional: When IsReaderTokenBacked is true. Must equal Card.
`cardData` required	all of CardData	Gets or sets the card data when `paymentMethodType` is Card. Required: When PaymentMethodType == Card and IsReaderTokenBacked is false. Conditional: When CardData is not null and PaymentMethodType == Card and IsReaderTokenBacked is false.
`checkData` required	all of CheckData	Gets or sets the check data when `paymentMethodType` is Check. Required: When PaymentMethodType == Check. Conditional: When CheckData is not null and PaymentMethodType == Check.
`isDefault` required	boolean	Gets or sets whether this should be the customer's default payment method.
`customName` required	string	Gets or sets an optional user-defined display name (e.g., "Marriott Chase"). nullable
`initialSchemeTransactionId` required	string	Optional initial (first-in-series) network / scheme transaction id captured from the authorization response of the cardholder-initiated transaction that stored this credential. Populated only on the transaction-driven save-card path (the manual Customer admin add has no authorization response); persisted onto the stored payment method so later charges can echo it without a consent lookup. Non-sensitive card-network protocol metadata. nullable
`schemeTransactionIdBrand` required	string	Optional card brand at capture time (e.g. "Visa") tagged alongside `initialSchemeTransactionId`. Ignored when the initial id is absent. nullable
`schemeTransactionIdProcessor` required	string	Optional originating processor ("tsys" / "fiserv") tagged alongside `initialSchemeTransactionId`. Ignored when the initial id is absent. nullable
`readerToken` required	string	The processor reader token to store for a PAN-less card (a decrypt-and-forward processor such as MagTek DAF, where the gateway never sees the PAN). When set, this input mints a reader-token stored method: the token is written encrypted onto the backing vault token's `ProcessorTokens` and there is no card data to vault. Set by the server only: a value supplied over the API is not accepted. Never logged. nullable
`readerTokenProcessorName` required	string	The processor key ("magtekdaf") the `readerToken` belongs to, used as the `ProcessorTokens` selection key. Required when `readerToken` is set. Required: When IsReaderTokenBacked is true. nullable
`readerTokenProcessorProfileId` required	string (uuid)	The processor profile the `readerToken` was captured under, used as the second part of the `ProcessorTokens` selection key. Optional. nullable
`readerTokenRequestorId` required	string	Optional token-requestor id captured alongside the `readerToken`. Stored on the backing token's `ProcessorTokens` entry for lineage. Non-sensitive. nullable
`readerTokenMaskedCardNumber` required	string	The masked card number of the card the `readerToken` stands in for, in the platform's masked shape (for example `411111******1111`), read off the approved authorization. Optional: absent when the processor response carried no card identity. Display only. It is never a charge credential and never a dedupe input (two distinct reader tokens can share a last four; `ReaderTokenFingerprint` stays the only matching key). The consuming services re-mask it before persisting, so a full PAN cannot travel through this field. Ignored unless `readerToken` is set. nullable
`readerTokenCardBrand` required	string	The card brand ("Visa", "Mastercard", ...) resolved for the card behind the `readerToken`, or `null` when neither the processor response nor the BIN lookup produced one. Best-effort display metadata; ignored unless `readerTokenMaskedCardNumber` is set. nullable
`isReaderTokenBacked` required	boolean	True when this input describes a reader-token (PAN-less) stored method rather than a PAN- or account-backed one. In that case `cardData` is absent by design. read only

This request body has no documented fields.