# JPMC-PDP Documentation from https://developer.payments.jpmorgan.com

# Request a token

This page describes how to request a Network or Safetech token for a payment instrument, and retrieve the token status and state information, token and card metadata details, and token asset details. 

## Before you begin

Familiarize yourself with [Network tokenization](/docs/commerce/optimization-protection/capabilities/tokenization/network-tokenization) and [Safetech tokenization](/docs/commerce/optimization-protection/capabilities/tokenization/safetech-tokenization).

## Required information

Before you proceed with requesting a network token, ensure that the following fields are present in your request body for card tokenization: 

 
**Required and conditionally-required fields for card tokenization by card brand**

| Payment brand | Required field | Conditional fields | 
| --- | --- | --- | 
| Visa | - AccountholderEmail - accountholderReference - cardNumber - cardExpiry - deviceLocale |  | 
| Mastercard | - cardNumber - cardExpiry |  | 
| American Express | - cardNumber - cardExpiry | One of the following fields must be provided: - accountholderEmail or accountholderTelephone - deviceIPAddress - required when cardSource field is not ONFILE. | 

## Request a network token

Request a network token by performing a `POST` call to the `/tokens` endpoint. 

**HTTP method**: `POST`
 **Endpoint**: `/tokens`

```json
{
    "device": {
        "deviceType": "PHONE",
        "deviceIPAddress": "127.0.0.1",
        "deviceLocale": "en-US",
        "deviceLatLong": "40, -73",
        "deviceMake": "Samsung",
        "deviceOS": "ANDROID",
        "deviceOsVersion": "12",
        "digitalDeviceIdentifier": "ahd896384d",
        "deviceGeoLocationCaptureTimestamp": "2021-09-08T21:01:20.945Z",
        "deviceName": "Samsung_Android",
        "walletId": "123"
    },
    "accountInformation": {
        "accountholderName": "John Doe",
        "accountholderEmail": "test@test.com",
        "accountType": "GUEST",
        "accountHolderReference": "e5ad0fd0-4f92-4df",
        "cardNumber": "5204740000001002",
        "billingAddress": {
            "addressLine1": "7825 N MacArthur Blvd",
            "addressLine2": "Lewisville Mall",
            "city": "Irving",
            "stateProvince": "TX",
            "postalCode": "72638",
            "countryCode": "US"
        },
        "cardExpiry": {
            "month": 11,
            "year": 2022
        },
        "cardSource": "KEY_ENTERED",
        "cardVerificationNumber": "325"
    },
    "riskInformation": {
        "walletRisk": {
            "walletScore": 15,
            "walletUsageLength": 94,
            "walletTransactions": 35,
            "walletNameMatch": true
        },
        "cardRisk": {
            "cardScore": 23,
            "cardUsageLength": 249
        },
        "deviceRisk": {
            "deviceScore": 19,
            "deviceUsageLength": 193,
            "deviceTokenCount": 2,
            "deviceCountry": "US"
        },
        "userRisk": {
            "userScore": 38,
            "userUsageLength": 49,
            "userTokenCount": 2,
            "userWalletCount": 1,
            "userCountry": "US",
            "newUserAccount": false,
            "onFileTime": 37
        }
    },
    "presentationModes": [
        "ECOM"
    ],
    "recommendationPath": "APPROVED"
}
```

**Response:**

```json
{
    "identifier": "fb0dabc0-da2c-46b6-b3a3-8fc6d3185e08",
    "timestamp": "2021-09-15T19:08:19.097",
    "tokenInformation": {
        "tokenNumber": "5000010000000019",
        "expiry": {
            "month": 11,
            "year": 2022
        },
        "tokenReferenceIdentifier": "af0a77c2-3810-457f-8d47-807bab406df8",
        "tokenizationApprovalStatus": "APPROVED",
        "cardReferenceNumber": "73ebcc62-56c0-41d2-b70a-4ede8cd700ff",
        "cardTokenStatus": "ACTIVE",
        "cardLast4Digits": "1002",
        "cardBrand": "MASTERCARD"
    },
    "cardMetaData": {
        "cardArtUrl": "http://cardArtUrl.com",
        "backgroundCardGraphicsColor": "#000000",
        "foregroundCardGraphicsColor": "#FFFFFF",
        "labelCardGraphicsColor": "#C0C0C0",
        "cardDescription": "The Bank Chase Card",
        "issuerInformation": {
            "cardIssuer": "Bank Example",
            "cardIssuerEmailAddress": "bank@example.com",
            "issuerWebsiteURL": "bank.com",
            "cardIssuerCustomerServiceTelephone": "400800393",
            "issuerOnlineBankingURL": "onlinebanking.com",
            "issuerIconURL": "http://logo.png",
            "issuerPrivacyURLText": "privacypolicybank.com",
            "issuerLogoURLText": "banklogo.com",
            "issuerApplicationOS": "IOS",
            "issuerAppName": "bankmobileapp",
            "issuerAppAddress": "com.bank.appname"
        },
        "cardShortDescription": "The Bank Card",
        "cardTermsAndConditionsIdentifier": "37629726-58cf-4fbb-a2bd-457614704be4",
        "cardTermsAndConditionsURL": "http://termsAndConditionsUrl.com",
        "cardAssetData": [
            {
                "assetReferenceIdentifier": "3801a454c0b84de883f5432815ded5f5",
                "assetType": "ICON_ISSUER",
                "mimeType": "IMAGE/PNG",
                "pixelHeight": 100,
                "pixelWidth": 100
            }
        ]
    },
    "requestIdentifier": "276ac797-8754-4ab8-a0b7-87da568e4d6d",
    "responseStatus": "SUCCESS",
    "responseCode": "APPROVED",
    "responseMessage": "The request is well received"
}
```

## Request a Safetech token

Request a network token by performing a `POST` call to the `/acquirertoken` endpoint.

**HTTP method**: `POST`
 **Endpoint**: `/acquirertoken`

```json
{
    "accountInformation": {
        "cardNumber": "379296848452209002",
        "cardSource": "KEY_ENTERED"
    }
}
```

**Response:**

```json
{
"identifier": "5bc5f837-b772-48f3-ad29-32fcdfe368ff",
"tokenInformation": {
     "acquirerTokenNumber": "379296576034739002"
  },
"responseStatus": "SUCCESS",
"responseCode": "ACCEPTED",
"responseMessage": "Request Accepted"
}
```

## Retrieve token information

Retrieve a token’s status and state information by performing a `GET` call to the `/tokens/{token-reference-id}` endpoint.

**HTTP method**: `GET`
 **Endpoint**: `/tokens/fb0dabc0-da2c-46b6-b3a3-8fc6d3190e98`

```json
{
  "identifier": "fb0dabc0-da2c-46b6-b3a3-8fc6d3190e98",
  "timestamp": "2021-09-15T19:52:48.801",
  "paymentInstrument": {
    "tokenReferenceIdentifier": "af0a77c2-3810-457f-8d47-807bab406df8",
    "cardTokenStatus": "ACTIVE",
    "stateChangeReason": "RESUME",
    "statusChangeTimestamp": "2021-09-15T19:52:48.801"
  },
  "requestIdentifier": "10cc0270-7bed-11e9-a188-1763956dd7f6",
  "responseStatus": "SUCCESS",
  "responseCode": "ACCEPTED",
  "responseMessage": "The request is well received."
}
```

## Retrieve token details

Retrieve the token and card metadata information in detail by performing a `GET` call to the `/tokens/{token-reference-id}/details` endpoint.

**HTTP method**: `GET`
 **Endpoint**: `/tokens/fb0dabc0-da2c-46b6-b3a3-8fc6d3190e88/details`

```json
{
    "identifier": "fb0dabc0-da2c-46b6-b3a3-8fc6d3185e08",
    "timestamp": "2022-09-09T19:08:19.097",
    "tokenInformation": {
        "tokenNumber": "340000000001000",
        "expiry": {
            "month": 11,
            "year": 2022
        },
        "tokenReferenceIdentifier": "af0a77c2-3810-457f-8d47-807bab406df8",
        "tokenizationApprovalStatus": "APPROVED",
        "cardReferenceNumber": "73ebcc62-56c0-41d2-b70a-4ede8cd700ff",
        "cardTokenStatus": "ACTIVE",
        "cardLast4Digits": "0001",
        "cardBrand": "VISA"
    },
    "cardMetaData": {
        "cardArtUrl": "http://cardArtUrl.com",
        "backgroundCardGraphicsColor": "#000000",
        "foregroundCardGraphicsColor": "#FFFFFF",
        "labelCardGraphicsColor": "#C0C0C0",
        "cardDescription": "The Bank Chase Card",
        "issuerInformation": {
            "cardIssuer": "Bank Example",
            "cardIssuerEmailAddress": "bank@example.com",
            "issuerWebsiteURL": "bank.com",
            "cardIssuerCustomerServiceTelephone": "400800393",
            "issuerOnlineBankingURL": "onlinebanking.com",
            "issuerIconURL": "http://logo.png",
            "issuerPrivacyURLText": "privacypolicybank.com",
            "issuerLogoURLText": "banklogo.com",
            "issuerApplicationOS": "IOS",
            "issuerAppName": "bankmobileapp",
            "issuerAppAddress": "com.bank.appname"
        },
        "cardShortDescription": "The Bank Card",
        "cardTermsAndConditionsIdentifier": "37629726-58cf-4fbb-a2bd-457614704be4",
        "cardTermsAndConditionsURL": "http://termsAndConditionsUrl.com",
        "cardAssetData": [
            {
                "assetReferenceIdentifier": "3801a454c0b84de883f5432815ded5f5",
                "assetType": "ICON_ISSUER",
                "mimeType": "IMAGE/PNG",
                "pixelHeight": 100,
                "pixelWidth": 100
            }
        ]
    },
    "requestIdentifier": "276ac797-8754-4ab8-a0b7-87da568e4d6d",
    "responseStatus": "SUCCESS",
    "responseCode": "APPROVED",
    "responseMessage": "The request is well received"
}
```

## Retrieve token asset details

Retrieve token asset details containing information about the card art by performing a `GET` call to the `/tokens/{token-reference-id}/assets/{asset-reference-id}` endpoint.

**HTTP method**: `GET`
 **Endpoint**: `/tokens/fb0dabc0-da2c-46b6-b3a3-8fc6d3190e88/assets/3801a454c0b84de883f5432815ded5f5`

```json
{
    "identifier": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "timestamp": "2022-09-11T15:25:35.950Z",
    "cardAssetData": [
        {
            "assetReferenceIdentifier": "3801a454c0b84de883f5432815ded5f5",
            "assetType": "ICON_ISSUER",
            "mineType": "IMAGE/PNG",
            "pixelHeight": 100,
            "pixelWidth": 100
        }
    ],
    "requestIdentifier": "10cc0270-7bed-11e9-a188-1763956dd7f6",
    "responseStatus": "SUCCESS",
    "responseCode": "ACCEPTED",
    "responseMessage": "Request Accepted"
}
```

## Related

[Network tokenization](/docs/commerce/optimization-protection/capabilities/tokenization/network-tokenization)
 [Safetech tokenization](/docs/commerce/optimization-protection/capabilities/tokenization/safetech-tokenization)
 [Request a cryptogram](/docs/commerce/optimization-protection/capabilities/tokenization/how-to/request-cryptograms)
 [Manage token state change](/docs/commerce/optimization-protection/capabilities/tokenization/how-to/token-states)