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

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

Example request

Every block below sends the same request. Replace {{BASE_URL}} with the address of the API you are calling and {{API_KEY}} with your own key.

The request body is a 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-09",
    "cardVerificationValue": "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-09",
    "cardVerificationValue": "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-09",
    "cardVerificationValue": "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-09",
      "cardVerificationValue": "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-09",
        "cardVerificationValue": "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-09",
        "cardVerificationValue": "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-09",
        "cardVerificationValue": "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-09",
    "cardVerificationValue": "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.