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

Adds customer stored payment method.

**Required permissions**: `Customers`, `Customers.Create`  
**Scope**: merchant

**Operation ID:** `POST_api_customers_add-stored-payment-method-async`

## Authorization

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

Required permissions:
- `Customers.Customers`
- `Customers.Customers.Create`

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| customerId | query | no | string(uuid) |  |
| suppressNulls | query | no | boolean | If true, omit properties with null values. |

## Request Body

**Content type:** `application/json`

Schema: `PhoeniXGateCustomersCustomersAddStoredPaymentMethodInput`

_Example: Add Card_

Adds a credit/debit card to the customer's stored payment methods. Set IsDefault = true to mark this as the customer's default payment method (any prior default is automatically demoted server-side).

```json
{
  "paymentMethodType": "Card",
  "cardData": {
    "cardNumber": "4111111111111111",
    "last4CardNumber": 1111,
    "expirationMonth": 0,
    "expirationYear": 0,
    "expirationDate": "2028-08-10",
    "binData": {
      "bin": 0,
      "issuedEntity": "Personal",
      "brand": null,
      "type": null,
      "category": null,
      "issuer": {
        "organization": null,
        "country": null,
        "countryCodeA2": null,
        "countryCodeA3": null,
        "countryNumber": null,
        "phone": null,
        "website": null
      },
      "panLength": null,
      "flags": {
        "regulated": false,
        "commercial": false,
        "healthcare": false,
        "government": null,
        "prepaid": null
      },
      "fundingSource": null
    },
    "cvv": 123,
    "nameOnCard": "Jane Smith",
    "pin": null,
    "keySerialNumber": null,
    "emvData": null,
    "trackData": null,
    "encryptedTrack1Data": null,
    "encryptedTrack2Data": null,
    "encryptedTrack3Data": null,
    "dynamicCardVerificationData": null,
    "dynamicCardVerificationStatus": null,
    "iin": null,
    "arqc": null,
    "entryMode": "Manual",
    "cvPresence": "None",
    "billingAddress": {
      "id": "040acc15-216f-4ba1-a5ff-faebe6666986",
      "address1": "456 Oak Ave",
      "address2": "",
      "city": "Reno",
      "state": "NV",
      "province": "",
      "zip": "89501",
      "postalCode": "",
      "country": "USA",
      "isMailing": false,
      "isDefault": false
    },
    "phone": null,
    "email": null,
    "hasEmvData": null,
    "hasTrackData": null,
    "hasEncryptedTrackData": null,
    "hasCvv": null,
    "hasPin": null,
    "hasDynamicCardVerificationData": null,
    "emvAid": null,
    "isDebitRouting": null,
    "tenderType": null,
    "isStoredPayment": null,
    "cryptogram": null,
    "eciIndicator": null,
    "isTokenized": null,
    "tokenTransactionId": null
  },
  "checkData": null,
  "isDefault": true,
  "customName": "Personal Visa",
  "initialSchemeTransactionId": null,
  "schemeTransactionIdBrand": null,
  "schemeTransactionIdProcessor": null,
  "readerToken": null,
  "readerTokenProcessorName": null,
  "readerTokenProcessorProfileId": null,
  "readerTokenRequestorId": null,
  "isReaderTokenBacked": false
}
```

_Example: Add ACH / eCheck_

Adds a US checking or savings account for ACH debits/credits. Routing + account numbers are required; the account is tokenized server-side.

```json
{
  "paymentMethodType": "Check",
  "cardData": null,
  "checkData": {
    "nameOnCheck": "Acme Corp",
    "routingNumber": "021000021",
    "accountNumber": "123456789",
    "checkNumber": null,
    "micr": null,
    "driversLicense": null,
    "state": null,
    "ssn": null,
    "dateOfBirth": null,
    "checkType": "Business",
    "accountType": "Checking",
    "rawMicr": null,
    "branchCity": null,
    "emailAddress": null,
    "telephoneNumber": null,
    "address": {
      "id": "4811f32a-2804-4f4b-92c8-8a64478869f5",
      "address1": "",
      "address2": "",
      "city": "",
      "state": "",
      "province": "",
      "zip": "",
      "postalCode": "",
      "country": "USA",
      "isMailing": false,
      "isDefault": false
    },
    "secCode": null,
    "isStoredPayment": null
  },
  "isDefault": false,
  "customName": "Operating Account",
  "initialSchemeTransactionId": null,
  "schemeTransactionIdBrand": null,
  "schemeTransactionIdProcessor": null,
  "readerToken": null,
  "readerTokenProcessorName": null,
  "readerTokenProcessorProfileId": null,
  "readerTokenRequestorId": null,
  "isReaderTokenBacked": false
}
```

**Content type:** `text/json`

Schema: `PhoeniXGateCustomersCustomersAddStoredPaymentMethodInput`

_Example: Add Card_

Adds a credit/debit card to the customer's stored payment methods. Set IsDefault = true to mark this as the customer's default payment method (any prior default is automatically demoted server-side).

```json
{
  "paymentMethodType": "Card",
  "cardData": {
    "cardNumber": "4111111111111111",
    "last4CardNumber": 1111,
    "expirationMonth": 0,
    "expirationYear": 0,
    "expirationDate": "2028-08-10",
    "binData": {
      "bin": 0,
      "issuedEntity": "Personal",
      "brand": null,
      "type": null,
      "category": null,
      "issuer": {
        "organization": null,
        "country": null,
        "countryCodeA2": null,
        "countryCodeA3": null,
        "countryNumber": null,
        "phone": null,
        "website": null
      },
      "panLength": null,
      "flags": {
        "regulated": false,
        "commercial": false,
        "healthcare": false,
        "government": null,
        "prepaid": null
      },
      "fundingSource": null
    },
    "cvv": 123,
    "nameOnCard": "Jane Smith",
    "pin": null,
    "keySerialNumber": null,
    "emvData": null,
    "trackData": null,
    "encryptedTrack1Data": null,
    "encryptedTrack2Data": null,
    "encryptedTrack3Data": null,
    "dynamicCardVerificationData": null,
    "dynamicCardVerificationStatus": null,
    "iin": null,
    "arqc": null,
    "entryMode": "Manual",
    "cvPresence": "None",
    "billingAddress": {
      "id": "040acc15-216f-4ba1-a5ff-faebe6666986",
      "address1": "456 Oak Ave",
      "address2": "",
      "city": "Reno",
      "state": "NV",
      "province": "",
      "zip": "89501",
      "postalCode": "",
      "country": "USA",
      "isMailing": false,
      "isDefault": false
    },
    "phone": null,
    "email": null,
    "hasEmvData": null,
    "hasTrackData": null,
    "hasEncryptedTrackData": null,
    "hasCvv": null,
    "hasPin": null,
    "hasDynamicCardVerificationData": null,
    "emvAid": null,
    "isDebitRouting": null,
    "tenderType": null,
    "isStoredPayment": null,
    "cryptogram": null,
    "eciIndicator": null,
    "isTokenized": null,
    "tokenTransactionId": null
  },
  "checkData": null,
  "isDefault": true,
  "customName": "Personal Visa",
  "initialSchemeTransactionId": null,
  "schemeTransactionIdBrand": null,
  "schemeTransactionIdProcessor": null,
  "readerToken": null,
  "readerTokenProcessorName": null,
  "readerTokenProcessorProfileId": null,
  "readerTokenRequestorId": null,
  "isReaderTokenBacked": false
}
```

_Example: Add ACH / eCheck_

Adds a US checking or savings account for ACH debits/credits. Routing + account numbers are required; the account is tokenized server-side.

```json
{
  "paymentMethodType": "Check",
  "cardData": null,
  "checkData": {
    "nameOnCheck": "Acme Corp",
    "routingNumber": "021000021",
    "accountNumber": "123456789",
    "checkNumber": null,
    "micr": null,
    "driversLicense": null,
    "state": null,
    "ssn": null,
    "dateOfBirth": null,
    "checkType": "Business",
    "accountType": "Checking",
    "rawMicr": null,
    "branchCity": null,
    "emailAddress": null,
    "telephoneNumber": null,
    "address": {
      "id": "4811f32a-2804-4f4b-92c8-8a64478869f5",
      "address1": "",
      "address2": "",
      "city": "",
      "state": "",
      "province": "",
      "zip": "",
      "postalCode": "",
      "country": "USA",
      "isMailing": false,
      "isDefault": false
    },
    "secCode": null,
    "isStoredPayment": null
  },
  "isDefault": false,
  "customName": "Operating Account",
  "initialSchemeTransactionId": null,
  "schemeTransactionIdBrand": null,
  "schemeTransactionIdProcessor": null,
  "readerToken": null,
  "readerTokenProcessorName": null,
  "readerTokenProcessorProfileId": null,
  "readerTokenRequestorId": null,
  "isReaderTokenBacked": false
}
```

**Content type:** `application/*+json`

Schema: `PhoeniXGateCustomersCustomersAddStoredPaymentMethodInput`

_Example: Add Card_

Adds a credit/debit card to the customer's stored payment methods. Set IsDefault = true to mark this as the customer's default payment method (any prior default is automatically demoted server-side).

```json
{
  "paymentMethodType": "Card",
  "cardData": {
    "cardNumber": "4111111111111111",
    "last4CardNumber": 1111,
    "expirationMonth": 0,
    "expirationYear": 0,
    "expirationDate": "2028-08-10",
    "binData": {
      "bin": 0,
      "issuedEntity": "Personal",
      "brand": null,
      "type": null,
      "category": null,
      "issuer": {
        "organization": null,
        "country": null,
        "countryCodeA2": null,
        "countryCodeA3": null,
        "countryNumber": null,
        "phone": null,
        "website": null
      },
      "panLength": null,
      "flags": {
        "regulated": false,
        "commercial": false,
        "healthcare": false,
        "government": null,
        "prepaid": null
      },
      "fundingSource": null
    },
    "cvv": 123,
    "nameOnCard": "Jane Smith",
    "pin": null,
    "keySerialNumber": null,
    "emvData": null,
    "trackData": null,
    "encryptedTrack1Data": null,
    "encryptedTrack2Data": null,
    "encryptedTrack3Data": null,
    "dynamicCardVerificationData": null,
    "dynamicCardVerificationStatus": null,
    "iin": null,
    "arqc": null,
    "entryMode": "Manual",
    "cvPresence": "None",
    "billingAddress": {
      "id": "040acc15-216f-4ba1-a5ff-faebe6666986",
      "address1": "456 Oak Ave",
      "address2": "",
      "city": "Reno",
      "state": "NV",
      "province": "",
      "zip": "89501",
      "postalCode": "",
      "country": "USA",
      "isMailing": false,
      "isDefault": false
    },
    "phone": null,
    "email": null,
    "hasEmvData": null,
    "hasTrackData": null,
    "hasEncryptedTrackData": null,
    "hasCvv": null,
    "hasPin": null,
    "hasDynamicCardVerificationData": null,
    "emvAid": null,
    "isDebitRouting": null,
    "tenderType": null,
    "isStoredPayment": null,
    "cryptogram": null,
    "eciIndicator": null,
    "isTokenized": null,
    "tokenTransactionId": null
  },
  "checkData": null,
  "isDefault": true,
  "customName": "Personal Visa",
  "initialSchemeTransactionId": null,
  "schemeTransactionIdBrand": null,
  "schemeTransactionIdProcessor": null,
  "readerToken": null,
  "readerTokenProcessorName": null,
  "readerTokenProcessorProfileId": null,
  "readerTokenRequestorId": null,
  "isReaderTokenBacked": false
}
```

_Example: Add ACH / eCheck_

Adds a US checking or savings account for ACH debits/credits. Routing + account numbers are required; the account is tokenized server-side.

```json
{
  "paymentMethodType": "Check",
  "cardData": null,
  "checkData": {
    "nameOnCheck": "Acme Corp",
    "routingNumber": "021000021",
    "accountNumber": "123456789",
    "checkNumber": null,
    "micr": null,
    "driversLicense": null,
    "state": null,
    "ssn": null,
    "dateOfBirth": null,
    "checkType": "Business",
    "accountType": "Checking",
    "rawMicr": null,
    "branchCity": null,
    "emailAddress": null,
    "telephoneNumber": null,
    "address": {
      "id": "4811f32a-2804-4f4b-92c8-8a64478869f5",
      "address1": "",
      "address2": "",
      "city": "",
      "state": "",
      "province": "",
      "zip": "",
      "postalCode": "",
      "country": "USA",
      "isMailing": false,
      "isDefault": false
    },
    "secCode": null,
    "isStoredPayment": null
  },
  "isDefault": false,
  "customName": "Operating Account",
  "initialSchemeTransactionId": null,
  "schemeTransactionIdBrand": null,
  "schemeTransactionIdProcessor": null,
  "readerToken": null,
  "readerTokenProcessorName": null,
  "readerTokenProcessorProfileId": null,
  "readerTokenRequestorId": null,
  "isReaderTokenBacked": false
}
```

## Responses

### 200

OK

**Content type:** `text/plain`

Schema: `PhoeniXGateCustomersCustomersCustomerStoredPaymentMethodDto`

**Content type:** `application/json`

Schema: `PhoeniXGateCustomersCustomersCustomerStoredPaymentMethodDto`

**Content type:** `text/json`

Schema: `PhoeniXGateCustomersCustomersCustomerStoredPaymentMethodDto`

### 403

Forbidden

**Content type:** `text/plain`

Schema: `WinkPGHttpRemoteServiceErrorResponse`

**Content type:** `application/json`

Schema: `WinkPGHttpRemoteServiceErrorResponse`

**Content type:** `text/json`

Schema: `WinkPGHttpRemoteServiceErrorResponse`

### 401

Unauthorized

**Content type:** `text/plain`

Schema: `WinkPGHttpRemoteServiceErrorResponse`

**Content type:** `application/json`

Schema: `WinkPGHttpRemoteServiceErrorResponse`

**Content type:** `text/json`

Schema: `WinkPGHttpRemoteServiceErrorResponse`

### 400

Bad Request

**Content type:** `text/plain`

Schema: `WinkPGHttpRemoteServiceErrorResponse`

**Content type:** `application/json`

Schema: `WinkPGHttpRemoteServiceErrorResponse`

**Content type:** `text/json`

Schema: `WinkPGHttpRemoteServiceErrorResponse`

### 404

Not Found

**Content type:** `text/plain`

Schema: `WinkPGHttpRemoteServiceErrorResponse`

**Content type:** `application/json`

Schema: `WinkPGHttpRemoteServiceErrorResponse`

**Content type:** `text/json`

Schema: `WinkPGHttpRemoteServiceErrorResponse`

### 501

Not Implemented

**Content type:** `text/plain`

Schema: `WinkPGHttpRemoteServiceErrorResponse`

**Content type:** `application/json`

Schema: `WinkPGHttpRemoteServiceErrorResponse`

**Content type:** `text/json`

Schema: `WinkPGHttpRemoteServiceErrorResponse`

### 500

Internal Server Error

**Content type:** `text/plain`

Schema: `WinkPGHttpRemoteServiceErrorResponse`

**Content type:** `application/json`

Schema: `WinkPGHttpRemoteServiceErrorResponse`

**Content type:** `text/json`

Schema: `WinkPGHttpRemoteServiceErrorResponse`

### 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. See the error-code reference in this document's description for the values `error.code` can take.

**Content type:** `application/json`

Schema: `WinkPGHttpRemoteServiceErrorResponse`

## See also

- [All documentation](https://docs.winkpg.io/llms.txt): the machine-readable index of every public page on this site.