Flow 1: Enrollment from X-Pay wallet

This flow is also known as In-App Verification.

This flow starts from the digital wallet app. The cardholder starts enrollment by scanning or entering the card information.

Green and Yellow paths

At the start of the enrollment, The provider assesses the cardholder risk.This risk level trigers these paths:

Color	workflow
	green path (a.k.a green flow): X-Pay provider approves the provisioning request autonomousl
	yellow path (a.k.a yellow flow): X-Pay provider asks the partner for a strong customer authentication
	orange path (a.k.a orange flow): X-Pay provider declines the provisioning request
	red path (a.k.a red flow): X-Pay provider declines the provisioning request

Only green and yellow paths are described below.

User journey

Action	Path	workflow
Scan or enter card number	green and yellow paths
Enter expiry date and CVV	green and yellow paths
Read and accept T&C 1 2 3	green and yellow paths
Choose verification method(call center, in-app, OTP SMS)	yellow path only
Open partner app	yellow path only
Log in to the partner app	yellow path only
Choose which card(s) to verify	yellow path only
X-Pay Enrollment confirmation message	yellow path only
X-Pay Enrollment confirmation notification	green and yellow paths

❗️

Step 4 must include in-app and OTP SMS (only applicable if partner wants to allow for Mac Book enrollment.

In this case, Partner must integrate webhook 26 and must implement an SMS server).

Sequence diagram (green path)

sequenceDiagram
autoNumber
    Actor Enduser
    participant Xpay Provider
    participant Xpollens
    participant Partner (Back end)
    participant Partner (App)
    
    Enduser -->> Xpay Provider: camera scan or manual input of card details <br/> (number, expiry date, CVV)
    Xpay Provider -->> Xpollens: Provisionning <br /> (does no impact end-user balances)
    Xpollens -->> Partner (Back end): Webhook Type 25 (status Active)

Sequence diagram (yellow path)

sequenceDiagram

autonumber

    Actor Enduser

    participant X-Pay provider

    participant Xpollens

    participant Partner(back-end)

    participant Partner(App)

    participant SCA_Provider

    

    Enduser ->> X-Pay provider: camera scan or manual input of card details<br/> (number, expiry date, CVV)

    X-Pay provider ->> Xpollens: Provisioning<br/> (does not impact end-user balances)

    

    Xpollens ->> Partner(back-end): Webhook Type 25 (status Inactive)

    X-Pay provider ->> Partner(App): App opening

    Partner(App) ->> Enduser: App connection

    

    Partner(back-end) ->> Xpollens: Get all tokens by card<br/>Checks if there are inactive tokens to verify

    Xpollens ->> Partner(back-end): Tokens status

    Partner(back-end) ->> Partner(App): Send card to activate

    Partner(App) ->> Enduser: Display card to activate

    Enduser ->> Partner(App): Choice of card to activate

    Partner(App) ->> SCA_Provider: Strong authentication notification

    SCA_Provider ->> Enduser: Strong authentication notification

    Enduser ->> SCA_Provider: SCA validated

    SCA_Provider ->> Partner(back-end): offline_authentication_token

    

    Partner(back-end) ->> Xpollens: In-App Verification Activation<br/>POST /api/sca/normal/v2.0/{{appUserId}}/token/xpayInAppVerifActivation/{{cardExternalRef}}<br/>with offline_authentication_token

    Xpollens -->> Xpollens: Business checks

    

    alt Business check KO

        Xpollens -->> Partner(back-end): HTTP 403<br/>Error: "The token does not meet the requirements for activation. The card is not in the right status or is blocked."

    else Business check OK

        Xpollens -->> Partner(back-end): HTTP 200, actionCode 00

    end

    

    Partner(back-end) -->> Partner(App): Card successfully added to X-Pay provider

    X-Pay provider ->> Xpollens: Provisioning<br/> (does not impact end-user balances)

    Xpollens ->> Partner(back-end): Webhook Type 25 (status Active)

In-App Verification Activation

This endpoint is useful only for Yellow flow. It must be called by the partner back end only if the user is strongly authenticated and approves the process.

POST /api/sca/normal/v2.0/{{appUserId}}/token/xpayInAppVerifActivation/{{cardExternalRef}}

Header

Request Body:

{
"tokenReferenceID": "string",
"tokenRequestorID": "string"
}

Read more about In-App Verification Activation here:

🔗 API Reference - Cards - Xpay

Token status diagram

stateDiagram
    [*] --> INACTIVE : token created
    
    INACTIVE --> ACTIVATED: token activated
    INACTIVE --> DELETED
    ACTIVATED --> DELETED : permanently deactivated
    ACTIVATED --> SUSPENDED : temporarily suspended
    SUSPENDED --> ACTIVATED
    
    DELETED --> [*]
    SUSPENDED --> [*]

The token status changes to SUSPENDED if:

• the card is temporarily blocked

The token status changes to DELETED if:

• the card is deleted from the wallet
• the card is opposed

General rules

A card can be added to the wallet as soon as its status is ACTIVATED.

If a token is not activated within 30 days of its creation, its status changes to DELETED.

During provisioning, VISA creates an authorization on the associated card. This authorization does not impact the user's balance and is not visible to either you or the end user.

In case of multiple tokens to activate, we recommend differentiating them by:

• Displaying the type of device used for enrollment
• Displaying the enrollment date.

📘

Note that our endpoint does not return this value. If needed, you have to integrate it when receiving the callback 25 with status "INACTIVE".

Apple pay in app verif

For Apple pay, the information needed by Xpollens are:

• the mobile banking app id, which is the team id + the bundle id
• the deeplink which redirect the enduser to the process in app verification (in your app)

Samsung & Google pay in app verif

For Samsung and Google pay, the information needed by Xpollens is the app bundleId.

Then the following actions have to be taken into account:

1. create the activity a2a in your app: this method must be named Package Name.a2a
2. use this activity to redirect the enduser to the in app verif process
3. redirect the enduser to the wallet

Find more details in these websites:

🔗https://developer.samsung.com/pay/ID&V/implementing-app2app-id&v.html
🔗https://developers.google.com/pay/issuers/tsp-integration/app-to-app-idv

How to test

The Xpay can not be tested in sandbox.
As a consequence, first tokenisation are processed in production, on whitelisted PANs.

Flow 2: Enrollment from partner app

This flow is also known as In-App Provisionning or Push Provisionning.

User journey

This flow starts from the partner app. The cardholder clicks on a button and no further interaction is needed from them. Xpollens recommends you implement this method for partners ordering virtual cards.

Add card to X-Pay Wallet
Choose device type(only smartphone and watch support this flow)
Confirm add card to X-Pay Wallet
Read and accept T&C 1 2 3
Card added to X-Pay Wallet

Sequence diagram

sequenceDiagram
autonumber
    Actor Enduser
    Participant Partner(iOS App)
    participant Mobile SDK
    participant Xpollens
    participant Xpay
    participant Partner(backend)
    
    Enduser ->> Partner(iOS App): Click on "Add to Apple Wallet"
    Partner(iOS App) ->> Mobile SDK : provisioning
    Mobile SDK ->> Xpollens: in-app provisionning <br/>  Xpollens IOS In-App Provisioning SDK
    Xpay ->> Xpollens: Provisionning <br/> (does not impact end-user balances)
    Xpollens ->> Partner(back-end):Webhook Type 25 (status Active)

Get all tokens by card

This endpoint retrieves the list of tokens for a specific card.

It must be requested in Flow 2 (enrollment from partner app), see sequence diagram above, message number 5.

GET /api/v2.0/token/card/{cardExternalRef}

Response Body:

[
    {
        "tokenValue": "4642353030722754",
        "tokenReferenceId": "DNITHE382003555876588856",
        "tokenRequestorId": "40010030273",
        "tokenExpiryDate": "11-2023",
        "tokenState": "ACTIVATED",
        "tokenType": "SECURE_ELEMENT",
        "tokenDeactivationDate": null,
        "tokenUpdateDate": "2020-12-28T16:54:50.6544932",
        "deviceInformation": {
            "secureElementId": null,
            "deviceType": null,
            "deviceNumber": null
        }
    },
    {
        "tokenValue": "4642353030898951",
        "tokenReferenceId": "DNITHE382003555876588857",
        "tokenRequestorId": "40010030273",
        "tokenExpiryDate": "10-2023",
        "tokenState": "INACTIVE",
        "tokenType": "SECURE_ELEMENT",
        "tokenDeactivationDate": null,
        "tokenUpdateDate": "2020-12-28T16:56:46.0778228",
        "deviceInformation": {
            "secureElementId": null,
            "deviceType": null,
            "deviceNumber": null
        }
    }
]

Partners should check the response body: for "tokenState": "ACTIVATED".

Then filter out only tokens having "tokenType": "SECURE_ELEMENT" (Apple Pay) or "tokenType": "HCE" (Samsung Wallet, Google Wallet)

Partners should display the push provisionning button (see below) only if there are no active X-Pay token associated with the card.

More information regarding this endpoint in the 🔗 API reference

Webhook Type 25

This Webhook is useful for all flows.

{
"id": "integer",              // internal Id, e.g. 637877811699419000
"reference": "string",        // card reference, a.k.a cardExternalRef or appCardId
"type": "integer",            // Webhook type, always equals to 25
"secureElementId": "string",  // deviceID, e.g. "44125A3342A80014272043036932204E3F73BB08847E90B"
"tokenValue": "string",       // token value (internal use only), e.g. "4642353030549437"
"tokenReferenceID": "string", // token unique Id, e.g. "DNITHE382003555876588856"
"tokenRequestorID": "string", // indicates the X-Pay provider: 
                              // * "40010030273" (Apple Pay)
                              // * "40010043095" (Samsung Wallet)
                              // * "40010075001" (Google Wallet)
"status": "string",           // token status:
                              // * "I" (Inactive)
                              // * "A" (Active)
                              // * "S" (Suspended)
                              // * "D" (Deleted)
"messageReasonCode": "string",//
}

Callback 25 messageReasonCode

One callback 25 is received for each event mentionned above.

Greenflow activation

sequenceDiagram
title: Greenflow
autonumber
    participant XPO
	participant Partner

Note over XPO, Partner: Token creation
	XPO -->> Partner: Callback 25 {status:I, messageReasonCode:1400}

Note over XPO, Partner: Token activation
	XPO -->> Partner: Callback 25 {status:A, messageReasonCode:1411}

Yellowflow activation

sequenceDiagram
title: Yellowflow
autonumber
    participant XPO
	participant Partner

Note over XPO, Partner: Token creation
	XPO -->> Partner: Callback 25 {status:I, messageReasonCode:1400}

Note over XPO, Partner: Activation needed through the in-app verification
	XPO -->> Partner: Callback 25 {status:I, messageReasonCode:1411}

Note over XPO, Partner: Token activation
	XPO -->> Partner: Callback 25 {status:A, messageReasonCode:1413}

In app provisioning

sequenceDiagram
autonumber
    participant XPO
	participant Partner

Note over XPO, Partner: Token creation
	XPO -->> Partner: Callback 25 {status:I, messageReasonCode:1400}

Note over XPO, Partner: Token activation
	XPO -->> Partner: Callback 25 {status:A, messageReasonCode:1411}

FAQ

FAQ1: Can I tokenise my card on multiple device?

Yes. You have one token per device used.

FAQ2: If an enduser tokenises its card on multiple device, how can I differ them?

Our application does not saved the type of device used. As a consequence, you must created a link on your own between the device, the deviceInformation and the token.