Store a card

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/customers/{customerId}/stored-cards \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "number": "ev:Tk9D:number:...$",
  "cvc": "ev:Tk9D:cvc:...$",
  "lastFour": "0005",
  "expiryMonth": 8,
  "expiryYear": 2029,
  "holderName": "Jane Doe",
  "billingAddress": {
    "line1": "123 Main Street",
    "postalCode": "94105",
    "country": "US",
    "line2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA"
  },
  "nickname": "Personal Visa"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    number: 'ev:Tk9D:number:...$',
    cvc: 'ev:Tk9D:cvc:...$',
    lastFour: '0005',
    expiryMonth: 8,
    expiryYear: 2029,
    holderName: 'Jane Doe',
    billingAddress: {
      line1: '123 Main Street',
      postalCode: '94105',
      country: 'US',
      line2: 'Apt 4B',
      city: 'San Francisco',
      state: 'CA'
    },
    nickname: 'Personal Visa'
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/customers/{customerId}/stored-cards', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"number\": \"ev:Tk9D:number:...$\",\n  \"cvc\": \"ev:Tk9D:cvc:...$\",\n  \"lastFour\": \"0005\",\n  \"expiryMonth\": 8,\n  \"expiryYear\": 2029,\n  \"holderName\": \"Jane Doe\",\n  \"billingAddress\": {\n    \"line1\": \"123 Main Street\",\n    \"postalCode\": \"94105\",\n    \"country\": \"US\",\n    \"line2\": \"Apt 4B\",\n    \"city\": \"San Francisco\",\n    \"state\": \"CA\"\n  },\n  \"nickname\": \"Personal Visa\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/customers/{customerId}/stored-cards")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "lastFour": "0005",
  "brand": "VISA",
  "funding": "CREDIT",
  "expiryMonth": 8,
  "expiryYear": 2029,
  "id": "StoredCard:019542f5-b3e7-1d02-0000-000000000077",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000010",
  "status": "ACTIVE",
  "holderName": "Jane Doe",
  "agentIds": [
    "Agent:019542f5-b3e7-1d02-0000-000000000042"
  ],
  "createdAt": "2026-11-06T15:00:00Z",
  "updatedAt": "2026-11-06T15:00:00Z",
  "issuerCountry": "US",
  "nickname": "Personal Visa",
  "billingAddress": {
    "line1": "123 Main Street",
    "postalCode": "94105",
    "country": "US",
    "line2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA"
  },
  "autoApprovals": [
    {
      "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
      "merchant": "example-store.com",
      "maxAmount": 4999,
      "currency": "USD"
    }
  ],
  "removedAt": "2026-11-07T09:30:00Z"
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "RATE_LIMITED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

Agent Management

Store a card

Store a card the customer already owns so the agents they choose can use it. Collect the card with Evervault’s Card UI component and send its ciphertext: a number or security code that is not Evervault ciphertext is refused with 400 INVALID_INPUT and never stored or logged.

Grid verifies the card with its issuer before storing it: the security code, billing address and name. A card the issuer does not confirm is refused with 400 STORED_CARD_VERIFICATION_FAILED. The security code is then discarded; Grid never stores it. The new card is shared with no agent: add one with PUT /customers/{customerId}/stored-cards/{storedCardId}/agents/{agentId}. Available where the platform enables stored cards, for individual customers.

POST

customers

{customerId}

stored-cards

Store a card

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/customers/{customerId}/stored-cards \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "number": "ev:Tk9D:number:...$",
  "cvc": "ev:Tk9D:cvc:...$",
  "lastFour": "0005",
  "expiryMonth": 8,
  "expiryYear": 2029,
  "holderName": "Jane Doe",
  "billingAddress": {
    "line1": "123 Main Street",
    "postalCode": "94105",
    "country": "US",
    "line2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA"
  },
  "nickname": "Personal Visa"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    number: 'ev:Tk9D:number:...$',
    cvc: 'ev:Tk9D:cvc:...$',
    lastFour: '0005',
    expiryMonth: 8,
    expiryYear: 2029,
    holderName: 'Jane Doe',
    billingAddress: {
      line1: '123 Main Street',
      postalCode: '94105',
      country: 'US',
      line2: 'Apt 4B',
      city: 'San Francisco',
      state: 'CA'
    },
    nickname: 'Personal Visa'
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/customers/{customerId}/stored-cards', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"number\": \"ev:Tk9D:number:...$\",\n  \"cvc\": \"ev:Tk9D:cvc:...$\",\n  \"lastFour\": \"0005\",\n  \"expiryMonth\": 8,\n  \"expiryYear\": 2029,\n  \"holderName\": \"Jane Doe\",\n  \"billingAddress\": {\n    \"line1\": \"123 Main Street\",\n    \"postalCode\": \"94105\",\n    \"country\": \"US\",\n    \"line2\": \"Apt 4B\",\n    \"city\": \"San Francisco\",\n    \"state\": \"CA\"\n  },\n  \"nickname\": \"Personal Visa\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/customers/{customerId}/stored-cards")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "lastFour": "0005",
  "brand": "VISA",
  "funding": "CREDIT",
  "expiryMonth": 8,
  "expiryYear": 2029,
  "id": "StoredCard:019542f5-b3e7-1d02-0000-000000000077",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000010",
  "status": "ACTIVE",
  "holderName": "Jane Doe",
  "agentIds": [
    "Agent:019542f5-b3e7-1d02-0000-000000000042"
  ],
  "createdAt": "2026-11-06T15:00:00Z",
  "updatedAt": "2026-11-06T15:00:00Z",
  "issuerCountry": "US",
  "nickname": "Personal Visa",
  "billingAddress": {
    "line1": "123 Main Street",
    "postalCode": "94105",
    "country": "US",
    "line2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA"
  },
  "autoApprovals": [
    {
      "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
      "merchant": "example-store.com",
      "maxAmount": 4999,
      "currency": "USD"
    }
  ],
  "removedAt": "2026-11-07T09:30:00Z"
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "RATE_LIMITED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

API token authentication using format <api token id>:<api client secret>

Path Parameters

customerId

string

required

System-generated unique customer identifier

Body

application/json

A card collected with Evervault's Card UI component. number and cvc must be Evervault ciphertext (strings starting ev:); a request carrying a plaintext value is refused with 400 and the value is never stored or logged. The CVC is used once, to verify the card with its issuer, and then discarded.

number

string

required

The card number, encrypted by Evervault's Card component.

Maximum string length: 2048

Pattern: ^ev:

Example:

"ev:Tk9D:number:...$"

cvc

string

required

The card's security code, encrypted by Evervault's Card component. Used only for the verification at add time; never stored.

Maximum string length: 2048

Pattern: ^ev:

Example:

"ev:Tk9D:cvc:...$"

lastFour

string

required

Last four digits of the number, as the Card component reports them.

Required string length: 4

Pattern: ^[0-9]{4}$

Example:

"0005"

expiryMonth

integer

required

Expiry month, 1 to 12.

Required range: 1 <= x <= 12

Example:

8

expiryYear

integer

required

Four-digit expiry year.

Required range: 2000 <= x <= 2199

Example:

2029

holderName

string

required

The name on the card.

Required string length: 1 - 255

Example:

"Jane Doe"

billingAddress

object

required

The card's billing address, checked against the issuer's records.

Show child attributes

nickname

string

The customer's own label for the card.

Maximum string length: 64

Example:

"Personal Visa"

Response

Card stored

A card the customer already owns, stored so their agents can use it. Grid holds the card number only as Evervault ciphertext: no Grid system stores, logs or returns the number itself.

lastFour

string

required

Last four digits of the card number.

Required string length: 4

Pattern: ^[0-9]{4}$

Example:

"0005"

brand

string

required

The card network, from the issuer's BIN data. Known values: VISA, MASTERCARD, AMERICAN_EXPRESS, DISCOVER, DINERS_CLUB, JCB, UNIONPAY, UNKNOWN. Treat an unrecognized value as UNKNOWN rather than an error.

Maximum string length: 32

Example:

"VISA"

funding

string

required

How the card is funded, from the issuer's BIN data. Known values: CREDIT, DEBIT, PREPAID, CHARGE, DEFERRED_DEBIT, UNKNOWN. Treat an unrecognized value as UNKNOWN rather than an error.

Maximum string length: 32

Example:

"CREDIT"

expiryMonth

integer

required

Expiry month, 1 to 12.

Required range: 1 <= x <= 12

Example:

8

expiryYear

integer

required

Four-digit expiry year.

Required range: 2000 <= x <= 2199

Example:

2029

string

required

System-generated unique identifier of the stored card.

Maximum string length: 64

Example:

"StoredCard:019542f5-b3e7-1d02-0000-000000000077"

customerId

string

required

The customer who owns the card.

Maximum string length: 64

Example:

"Customer:019542f5-b3e7-1d02-0000-000000000010"

status

enum<string>

required

Status	Description
`ACTIVE`	The card can be used by the agents it is shared with
`REMOVED`	The customer removed the card. Grid erased its encrypted number, holder name and billing address; only the display fields remain

Available options:

ACTIVE,

REMOVED

holderName

string

required

The cardholder name, as the customer entered it. Empty once the card is REMOVED.

Maximum string length: 255

Example:

"Jane Doe"

agentIds

string[]

required

The agents the customer allowed to use this card. An agent also needs the USE_STORED_CARDS permission. Empty once the card is REMOVED.

Maximum array length: 100

Maximum string length: 64

createdAt

string<date-time>

required

When the card was stored.

Example:

"2026-11-06T15:00:00Z"

updatedAt

string<date-time>

required

When the card was last changed.

Example:

"2026-11-06T15:00:00Z"

issuerCountry

string

ISO 3166-1 alpha-2 country of the card's issuer, when the BIN data names one.

Required string length: 2

Example:

"US"

nickname

string

The customer's own label for the card.

Maximum string length: 64

Example:

"Personal Visa"

billingAddress

object

The card's billing address. Absent once the card is REMOVED.

Show child attributes

autoApprovals

object[]

Merchants where the customer chose to let an agent use the card without asking again, each up to an amount. Cleared for an agent when its access is removed. Empty once the card is REMOVED.

Maximum array length: 100

Show child attributes

removedAt

string<date-time>

When the customer removed the card. Present only once it is REMOVED.

Example:

"2026-11-07T09:30:00Z"

Using the API

API documentation

Store a card

Authorizations

Path Parameters

Body

Response