# Data Vault Tokenisation

# Creating a token

To generate a Token for future use at the same time as submitting a payment, use the `createToken` object to set a Token up for multiple use (set `reusable` to "true"). In addition, you can set rules as to whether you want to decline payments with duplicate payment details (set `declineDuplicates`).

To tokenise a payment card separately to a payment, POST the payload to `/payment-tokens` [endpoint](https://docs.fiserv.dev/public/reference/createpaymenttoken).

If you supply a token value, we will store that, otherwise we'll generate a token value and pass it back to you in the response.

The following JSON document represents the examples of requests and response for token only creation:

```json Request
{
  "requestType": "PaymentCardPaymentTokenizationRequest",
  "paymentCard": {
    "number": "4012000033330026",
    "expiryDate": {
      "month": "12",
      "year": "29"
    }
  },
  "createToken": {
    "reusable": true,
    "declineDuplicates": false
  },
  "accountVerification": false,
  "additionalDetails": {
    "operatorId": "OPERATOR_ID_123XXX",
    "salesSystemId": "W-EU-H3866-FLS2"
  }
}
```
```json Response
{
    "clientRequestId": "7ea3415f-62ba-4a1f-8c0f-3c933c1e0c87",
    "apiTraceId": "Y7gIvGrWgLTPAUE7rGOJaQAAAso",
    "requestStatus": "SUCCESS",
    "requestTime": 1673005244065,
    "country": "United Kingdom",
    "paymentToken": {
        "value": "838C36B4-133E-4068-BF50-99008A0DB003",
        "reusable": true,
        "declineDuplicates": false,
        "last4": "0026",
        "brand": "MASTERCARD",
        "type": "PAYMENT_CARD"
    },
    "orderId": "R-e0b9cc9c-730b-4064-b81b-ff84327ce7ac",
    "ipgTransactionId": "84616111269"
}
```

In the above example, we are allowing our systems to generate a payment token for the given card details, and it sends it back with the value `838C36B4-133E-4068-BF50-99008A0DB003` for later use.

If you wish to set your own value for the token, include the `value` attribute in the `createToken` object. If you do not include this, we will define the token value and return it in the response as `value` attribute in the `paymentToken` object. If set to true, the token can be reused. If false, it has only a single use.

# Updating a token

You can update one or more tokens at a time, and change the settings for the token or the payment card associated with the Token. To make these updates, make a **PATCH** to `/payment-tokens` using `requestType`=`PaymentCardPaymentTokenUpdateRequest`.

The `PaymentTokens` object is a list, and can include multiple payment tokens. See the example below to see how to construct the payload. Each of the token objects below includes the updates required - these will automatically be written to the token record on our systems if the request is processed successfully.

```json Request
{
  "requestType": "PaymentCardPaymentTokenUpdateRequest",
  "paymentTokens": [
    {
      "value": "1751905117310026",
      "reusable": true,
      "declineDuplicates": false,
      "paymentCard": {
        "number": "5424180279791732",
        "expiryDate": {
          "month": "03",
          "year": "27"
        },
        "securityCode": "XXX"
      }
    },
    {
      "value": "9877hkhk68688888ffgh",
      "reusable": true,
      "declineDuplicates": false,
      "paymentCard": {
        "number": "4773410012347324",
        "expiryDate": {
          "month": "12",
          "year": "27"
        },
        "securityCode": "XXX"
      }
    }
  ]
}
```
```json Partial Success Response
{
  "requestStatus": "PARTIAL_SUCCESS",
  "requestTime": "1554308829345",
  "errors": {
    "details": [
      {
        "message": "HOSTED_DATA_ID4773410012347324. Invalid credit card number: CreditCard [cardNumber=4773410...7324, expirationMonth=12, expirationYear=2026"
      },
    ]
  }
}
```

# Using a token

Once the token is created and you have stored it against the customer’s account detail, you can use it to execute payments for the customer. To use a tokenised payment instrument, use the relevant `PaymentToken*` requestType.

```json Request
{
  "requestType": "PaymentTokenSaleTransaction",
  "transactionAmount": {
    "total": 12.04,
    "currency": "EUR"
  },
  "paymentMethod": {
    "paymentToken": {
      "value": "1235325235236",
      "function": "DEBIT",
      "securityCode": "977"
    }
  }
}
```

When a customer is checking out, and you've previously tokenised their payment details mapped to their account, you can request token details to enable the customer to confirm they want to pay with the stored payment instrument.

To do this, use the GET endpoint, providing the `tokenid` to receive a PaymentTokenDetails response. Our suggestion is you use the `last4` value and `brand` to enable the customer to correctly identify which payment instrument they wish to use, and then from there you can use the token value as in the example above.