X-Pay

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:

• ■ green path (a.k.a green flow): X-Pay provider approves the provisioning request autonomously
• ■ 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

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

Please note that 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)

Sequence diagram (yellow path)

Step 7 (In-App Verification Activation) and step 12 (Webhook Type 25) are described below.

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/v2.0/token/{cardExternalRef}/XPayInAppVerifActivation

Request Body:

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

Read more about In-App Verification Activation here: API Reference - Cards - Xpay

Try it out

---

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.

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

Sequence diagram

Please note that Step1 is done with an SDK (software Development Kit) provided by Xpollens. See the related documentation here

---

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

Try it out

Webhook Type 25

This Webhook is useful for all flows.

Xpollens sends this Webhook to partners in case of a token status change. Partners should act upon "status": "A" and ignore any other values.

"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" (Deactivated)
"messageReasonCode": "string",// useless for partners, e.g. null or "1400" (token created)

Read more about Webhooks here: Callbacks OpenAPI