# Digital Wallet Tokens
> A Digital Wallet Token is created when a user adds a Card to their Apple Pay or Google Pay app. The Digital Wallet Token can be used for purchases just like a Card.

[Events](https://increase.com/documentation/events.md) will be generated for this resource. The possible event categories are: `digital_wallet_token.created`  and `digital_wallet_token.updated`.

## The Digital Wallet Token object
### Example
```json
{
  "card_id": "card_oubs0hwk5rn6knuecxg2",
  "cardholder": {
    "name": "John Smith"
  },
  "created_at": "2020-01-31T23:59:59Z",
  "device": {
    "device_type": "mobile_phone",
    "identifier": "04393EADF4149002225811273840459271E36516DA4875FF",
    "ip_address": "1.2.3.4",
    "name": "My Work Phone"
  },
  "dynamic_primary_account_number": null,
  "id": "digital_wallet_token_izi62go3h51p369jrie0",
  "status": "active",
  "token_requestor": "apple_pay",
  "type": "digital_wallet_token",
  "updates": [
    {
      "status": "inactive",
      "timestamp": "2020-01-31T23:59:59Z"
    }
  ]
}
```
### Attributes
- `card_id` (string)
  The identifier for the Card this Digital Wallet Token belongs to.

- `cardholder` (dictionary)
  The cardholder information given when the Digital Wallet Token was created.

  - `cardholder.name` (string, nullable)
    Name of the cardholder, for example "John Smith".

- `created_at` (string)
  The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the Digital Wallet Token was created.

- `device` (dictionary)
  The device that was used to create the Digital Wallet Token.

  - `device.device_type` (enum, nullable)
    Device type.
    Cases:
    * `unknown` (Unknown)
    * `mobile_phone` (Mobile Phone)
    * `tablet` (Tablet)
    * `watch` (Watch)
    * `mobilephone_or_tablet` (Mobile Phone or Tablet)
    * `pc` (PC)
    * `household_device` (Household Device)
    * `wearable_device` (Wearable Device)
    * `automobile_device` (Automobile Device)

  - `device.identifier` (string, nullable)
    ID assigned to the device by the digital wallet provider.

  - `device.ip_address` (string, nullable)
    IP address of the device.

  - `device.name` (string, nullable)
    Name of the device, for example "My Work Phone".

- `dynamic_primary_account_number` (dictionary, nullable)
  The redacted Dynamic Primary Account Number.

  - `dynamic_primary_account_number.first6` (string)
    The first 6 digits of the token's Dynamic Primary Account Number.

  - `dynamic_primary_account_number.last4` (string)
    The last 4 digits of the token's Dynamic Primary Account Number.

- `id` (string)
  The Digital Wallet Token identifier.

- `status` (enum)
  This indicates if payments can be made with the Digital Wallet Token.
  Cases:
  * `active` (The digital wallet token is active.)
  * `inactive` (The digital wallet token has been created but not successfully activated via two-factor authentication yet.)
  * `suspended` (The digital wallet token has been temporarily paused.)
  * `deactivated` (The digital wallet token has been permanently canceled.)

- `token_requestor` (enum)
  The digital wallet app being used.
  Cases:
  * `apple_pay` (Apple Pay)
  * `google_pay` (Google Pay)
  * `samsung_pay` (Samsung Pay)
  * `unknown` (Unknown)

- `type` (string)
  A constant representing the object's type. For this resource it will always be `digital_wallet_token`.

- `updates` (array of objects)
  Updates to the Digital Wallet Token.

  - `updates.status` (enum)
    The status the update changed this Digital Wallet Token to.
    Cases:
    * `active` (The digital wallet token is active.)
    * `inactive` (The digital wallet token has been created but not successfully activated via two-factor authentication yet.)
    * `suspended` (The digital wallet token has been temporarily paused.)
    * `deactivated` (The digital wallet token has been permanently canceled.)

  - `updates.timestamp` (string)
    The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time at which the update happened.

## List Digital Wallet Tokens
GET /digital_wallet_tokens

### Example
```curl
curl \
  --url "${INCREASE_URL}/digital_wallet_tokens?card_id=card_oubs0hwk5rn6knuecxg2" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```

### Query Parameters
- `cursor` (string, optional)
  Return the page of entries after this one.

- `limit` (integer, optional)
  Limit the size of the list that is returned. The default (and maximum) is 100 objects.

- `card_id` (string, optional)
  Filter Digital Wallet Tokens to ones belonging to the specified Card.

- `created_at.after` (string, optional)
  Return results after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

- `created_at.before` (string, optional)
  Return results before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

- `created_at.on_or_after` (string, optional)
  Return results on or after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

- `created_at.on_or_before` (string, optional)
  Return results on or before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

### Returns a Digital Wallet Token List object:
```json
{
  "data": [
    {
      "card_id": "card_oubs0hwk5rn6knuecxg2",
      "cardholder": {
        "name": "John Smith"
      },
      "created_at": "2020-01-31T23:59:59Z",
      "device": {
        "device_type": "mobile_phone",
        "identifier": "04393EADF4149002225811273840459271E36516DA4875FF",
        "ip_address": "1.2.3.4",
        "name": "My Work Phone"
      },
      "dynamic_primary_account_number": null,
      "id": "digital_wallet_token_izi62go3h51p369jrie0",
      "status": "active",
      "token_requestor": "apple_pay",
      "type": "digital_wallet_token",
      "updates": [
        {
          "status": "inactive",
          "timestamp": "2020-01-31T23:59:59Z"
        }
      ]
    }
  ],
  "next_cursor": "v57w5d"
}
```

## Retrieve a Digital Wallet Token
GET /digital_wallet_tokens/{digital_wallet_token_id}

### Example
```curl
curl \
  --url "${INCREASE_URL}/digital_wallet_tokens/digital_wallet_token_izi62go3h51p369jrie0" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `digital_wallet_token_id` (string, required)
  The identifier of the Digital Wallet Token.

## Sandbox: Create a digital wallet token request
POST /simulations/digital_wallet_token_requests
> Simulates a user attempting to add a [Card](#cards) to a digital wallet such as Apple Pay.
### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/simulations/digital_wallet_token_requests" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "card_id": "card_oubs0hwk5rn6knuecxg2"
  }'
```

### Body Parameters
- `card_id` (string, required)
  The identifier of the Card to be authorized.

### Returns a Inbound Digital Wallet Token Request Simulation Result object:
```json
{
  "decline_reason": null,
  "digital_wallet_token_id": "digital_wallet_token_izi62go3h51p369jrie0",
  "type": "inbound_digital_wallet_token_request_simulation_result"
}
```