> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/tokenization/integrate-in-app-id-and-v.md).

# Integrate in-app ID\&V

The End User might be asked by the token requestor to perform a verification under two essential circumstances:

1. during a tokenization flow. Upon the request to tokenize a card and a subsequent decision to approve with a step-up. This happen in the case a token for proximity payment is requested.
2. in a post-tokenization flow. This occurs only for e-commerce tokens. Essentially, the merchant can trigger a request for a verification and if the issuer approves with a step-up request, the in-app method can be used.

In general, the user journey is displayed in the following picture:

<figure><img src="https://content.gitbook.com/content/W6dljaTEEzefPQILRFB7/blobs/umFLV1mnjIqRfuphC4NO/UX%20%20%20Push%20to%20Wallet.svg" alt=""><figcaption><p>App-to-app ID&#x26;V flow.</p></figcaption></figure>

The digital wallet launches the issuer application for step-up authentication for any of the reason above mentioned:

* Step 1: Choose in-app ID\&V. The End User selects **Sign in to the bank app**.
* Step 2: Authenticate. The End User signs in to the issuer application.
* Step 3: If required, confirm the card. Show the last four digits of the PAN. The End User confirms activation.
* Step 4: Confirm the verification result.
* Step 5: Return to the wallet to confirm success.

Once the End User selects the in-app method for ID\&V, the digital wallet application must redirect the flow to the issuer application.

To do this, the TSP provides the following redirection information:

* The issuer application reference (configured by the issuer in the TSP during onboarding).
* An opaque payload that describes the reason for the ID\&V request.

This section provides a guideline regarding :

* The information the issuer must provide to the TSP (application metadata).
* How to handle the redirection call from the digital wallet application.

{% hint style="info" %}
Please note that for an exhaustive information about the TSP configuration, the issuer must consult the scheme.
{% endhint %}

The diagram below shows, at a high level, the main steps involved for such type of interaction between a digital wallet and the issuer application:

<figure><img src="https://content.gitbook.com/content/W6dljaTEEzefPQILRFB7/blobs/MeySOtsF8zGk5kBacCgt/Integrate%20in%20app%20ID&amp;V%20for%20xPay%20Wallets.svg" alt=""><figcaption><p>In-app ID&#x26;V redirection flow for xPay Wallets.</p></figcaption></figure>

1. During onboarding, the issuer configures the application metadata in the TSP.
2. During Tokenization, when step-up authentication is required, the TSP provides the following data along with the method type:
   1. issuer application reference
   2. opaque payload
3. The digital wallet application uses the issuer application reference to open the issuer application. It passes the opaque payload in the call.
4. The issuer application parses the opaque payload to understand the request. It then prompts the End User to enter credentials.
5. The issuer application verifies the credentials.
6. The issuer application returns the verification result to the issuer backend.
7. The issuer backend reports the result to the TSP.

The opaque payload is essentially a base64 string that encodes a JSON object formatted by the TSP scheme.

The content of this object is not sensitive, so the only operation that the issuer has to do is to decode the base64 format and interpred the JSON fields.

The fields allow the issuer to identify the context for which the verification is required.

Below few examples extracted from the scheme's documentation.

{% hint style="info" %}
For full details is adviced to verify the dedicated documentation from the the schemes.
{% endhint %}

### Visa

Use case: tokenization

```json
{
  "panReferenceID":"V-3815023863409817870482",
  "tokenRequestorID":"42301999123",
  "tokenReferenceID":"DNITHE381502386342002358",
  "panLast4":"1234",
  "deviceID":"DEiOiJBMjU2R_0NNS1-ciLCJiI",
  "walletAccountID":"AiOiJBMjU-2_R0NNS1ciLCJiI6"
}
```

Use case: device binding

```json
{
 "panReferenceID": "V38202107121853123XXXXX",
 "tokenRequestorID": "400100XXXXX",
 "tokenReferenceID": "DNITHE3820226686801XXXXX",
 "panLast4": "6301",
 "walletAccountID": "AWMTE9aPXFBM3yddqpE_kzf-",
 "deviceID": "0ff81e66b98e0e3f7d91b76b",
 "deviceIndex": "1",
 "reasonCode": "TOKEN_DEVICE_BINDING"
 }
```

Use case: cardholder verification

```json
{"panReferenceID":"V38202107121853123XXXXX",
"tokenRequestorID":"400100XXXXX",
"tokenReferenceID":"DNITHE3820226686801XXXXX",
"panLast4":"6301",
"walletAccountID":"AWMTE9aPXFBM3yddqpE_kzf-",
"deviceID": null,
"deviceIndex": null,
"reasonCode": "CARDHOLDER_STEPUP",
"lifeCycleTraceID": "773871594125753"
}
```

### Mastercard

Use case: tokenization

```json
{
  "paymentAppProviderId": "123456789",
  "paymentAppInstanceId": "123456789",
  "tokenUniqueReference": "DWSPMC000000000fcb2f4136b2f4136a0532d2f4136a0532",
  "accountPanSuffix": "6789",
  "accountExpiry": "1018"
}
```

Use case: device binding

```json
{
 "paymentAppProviderId" : "23404332",
 "authenticationCorrelationId" : "23aerkeskew48943040",
 "tokenUniqueReference" : "23430iejfoijwe0404",
 "accountPanSuffix": "2345",
 "accountExpiry" : "1222"
}
```

Optionally, the issuer can rely on D1 SDK to parse the JSON object provided by the digital wallet. This can be used by in all the cases whereas the digital wallet does not manipulate the JSON object in some ways. For example, this can't used for Apple Pay. See details in the section Integration with Apple Pay.

{% hint style="info" %}
**Note**

The integration of D1 SDK implies additional fees. For more details, check with your point of contact in Thales.
{% endhint %}

#### CODE snippet

### Mapping the fields with D1 fields

The following mapping rules apply:

D1 `digitalCardId`:

* Visa: `tokenReferenceID`.
* Mastercard: `tokenUniqueReference`.

Post-tokenization use cases:

D1 `authenticationId`:

* Token binding
  * Visa: `deviceIndex`
  * Mastercard: `authenticationCorrelationId`
* Cardholder verification
  * Visa: `lifeCycleTraceId`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.payments.thalescloud.io/tokenization/integrate-in-app-id-and-v.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
