Card activation

Physical cards can be activated by two ways:

1. By withdrawing money from an ATM or by making a local payment using a pin code
2. By API through

Before activation, the card status is "Sent". As soon as the card is used, the status changed for "Activated".

This status is visible in the webdesk, and a CardCreatedOrUpdated is received.

📘

VAD (Distance selling) is available as soon as the card status is activated.

---

Card cancellation

Card cancellation is most often used when closing an account, or when the user changes their mind and wants to cancel an order. However, the functionality is available throughout the entire lifecycle.

The status changes to 'CANCELED'.

🔗POST /api/V3.0/cards/cardId/cancel

---

Card opposition

Card opposition is available via API and the webdesk, or by calling the VISA call center.

Opposition by the webdesk is only possible for users with a senior profile, or for customised profiles with write access to this section.

Status

As soon as the card is opposed, the status changed to "OPPOSED". This information is sent thourgh the CardCreatedOrUpdated.

This action is immediate and irreversible.

If a new card is needed, POST /api/v3.0/cards has to be used (renvoyer vers le use case création de carte)

API, Callbacks & technical items

🔗POST /api/v3.0/cards/cardId/oppose

---

Card remanufacturing

👍

If the card is faulty or does not work, you must ask for it to be remanufactured.

The former card is automatically 'Deactivated' as soon as the new card is 'Activated'.

API, Callbacks & technical items: 🔗POST /api/v3.0/cards/refabricate

---

Card expiration

The card's validity period is configured when the environment is created.

Case: card not renewed

As soon as the card expires, the status changes to "EXPIRED" and a CardCreatedOrUpdated is sent.

Case: card renewed

The card renewal is not automatic. You must place the order.

The card can be ordered even if there is already an active card. However, once the replacement card is activated, the old card automatically changes for the status DEACTIVATED.

---

Card information changes depending on the event

👍

For cancellation, opposition, if a new card is needed:

1. by API : order a new card with the POST /api/v3.0/cards and ask for the wishpin
2. by webdesk (the new card is systematically with a random pin)

---

Selfcare

Limits

There are 2 limits on bank cards:

• ATM limits
• Payment limit

For each limit, 2 values are configured when environments are created:

1. the default amount
2. the maximum amount

Customisation by user is then carried out via API (or webdesk).

ATM limits

The withdrawal limit is for 7 calendar days. Update this limit: 🔗 PUT /api/v2.0/card/cardExternalRef Retrieve the limit value and the used allowance: 🔗 GET /api/v3.0/cards/cardId

Payment limits

Monthly

The payment limit is 30 calendar days (FR UTC)

Daily

The daily payment is calculated on a daily basis. It is reset every day at midnight, French mainland time.

Keep in mind the rule: Daily payment < or = Monthly payment

Webhook

For each limit change, you receive a webhook.

---

Temporary blocking

Please note: temporary blocking is not a change in card status, but in one of its attributes. Therefore, changing the boolean does not send a callback 21. The request response has to be integrated in the partner's refential.

Once a card is blocked, all card transactions are impossible.

API

🔗PATCH /api/v3.0/cards/selfcare/cardId : field isFrozen. 🔗GET /api/v3.0/cards/cardId : field isFrozen.

Webdesk

A card can be blocked temporary through the webdesk for profil "senior operator".

---

Geoblocking

❗️

temporary blocking is not a change in card status, but is one of its attributes.

API

🔗PATCH /api/v3.0/cards/selfcare/cardId isInternationalPaymentEnabled 🔗GET /api/v3.0/cards/cardId: isInternationalPaymentEnabled

Webdesk

This feature is also available through the webdesk for profil "senior operator"

---

VAD

👍

The VAD is activated by default in the configuration of your environments.

If you don't want it to be available when the card is created, you need to call up the api to change the Boolean value.

🔗PATCH /api/v3.0/cards/selfcare/cardId: isEcomPaymentEnabled 🔗GET /api/v3.0/cards/cardId: isEcomPaymentEnabled

---

PIN

👍

The get pin can be tested in all environments, whether the environment is mocked or not.

However, on mocked environments, the response is mocked and will always return the same value.

Mobile initiatedauthenticationflow chart

In this workflow, the user’s strong authentication is processed through the SDK prior to the Xpollens API call. The authentication proof shall be then provided as an input (header) of the corresponding Xpollens APIs (Secure PIN display, Secure PAN/CVV/Expiry date Display) wich work in a synchronous mode.

sequenceDiagram
autoNumber
Participant User
Participant Mobile App
Participant SDK SCA.Provider
Participant Xpollens
User ->> Mobile App : sensitive operation 
Mobile App ->> SDK SCA.Provider: Authenticate
SDK SCA.Provider ->> Mobile App: Notify authentication required
Mobile App ->> User: Display notification message
User ->> Mobile App: Accept authentication
Mobile App ->> SDK SCA.Provider: Authentication data
SDK SCA.Provider ->> SDK SCA.Provider : Validate authentication
SDK SCA.Provider ->> SDK SCA.Provider : Generate authentication proof
SDK SCA.Provider ->> Mobile App: Callback authentication result {authentication proof}
Mobile App ->> Xpollens: sensitive operation <br/> Secure display PIN <br/> Secure display card
Xpollens ->> Xpollens: Validate authentication proof
Xpollens ->> Xpollens: Execute sensitive operation

❗️

Xpollens APIs which require the mobile initiated authentication contains « /sca/normal » in the signature

The authentication proof (= JWS token =offline_authentication_token) contains a public key used by Xpollens to encypher sensitive data (PIN, PAN&CVV)

The SDK will then use the private key to decypher the secure payload, and display the sensitive info on the mobile app.

🔗https://doc.antelop-solutions.com/latest/wallet/sca/sca-intro.html#_mobile_initiated_authentication

🔗GET /api/sca/normal/v2.0/holderExternalRe}/pin/cardExternalRef?channelCode=XX

Secure Display – Pin Display

Pre-requisites:

• Get the « offline_authentication_token » through the SDK
• Card status should be ‘sent’ or ‘Activated

Inputs

Ouput

Secure Display – Pin Display flow chart for Android

sequenceDiagram
autoNumber
Participant Back as Partner_BackEnd 
Participant Front as  Partner_FrontEnd 
Participant SDK as SCA.Provider.SDK 
Participant Xpollens
Front ->> SDK: Client authentication
SDK ->> SDK : JWS generated with the SDK private key
SDK -->> Front: JWS
Front -->> Back: JWS
Back -->> Xpollens: Diplay Pin <br/> The proof of authentication should be transmitted in the header (cf. below)
Xpollens ->> Xpollens: JWE generated and encrypted with the public key extracted from JWS
Xpollens -->> Back : Secure payload
Back -->> SDK : Secure payload
SDK -->> SDK: JWE decryption with the private key
SDK -->> Front: Display pin

for 8, for more details refer to 🔗 https://doc.antelop-solutions.com/latest/common/sdk-javadoc/fr/antelop/sdk/ui/securedisplay/package-summary.html

Secure Display – Pin Display flow chart for iOS

sequenceDiagram
autoNumber
Participant Back as Partner_BackEnd 
Participant Front as  Partner_FrontEnd 
Participant SDK as SCA.Provider.SDK 
Participant Xpollens
Front ->> SDk : Wallet.getSecureDisplayCertificat
SDK ->> Front: SDK private key
Front ->> Back: SDK private key
Front ->> SDK: Client authentication
SDK ->> SDK : JWS generated with the SDK private key
SDK -->> Front: JWS
Front -->> Back: JWS
Back -->> Xpollens: Diplay Pin <br/> The proof of authentication should be transmitted in the header (cf. below)
Xpollens ->> Xpollens: JWE generated and encrypted with the public key extracted from JWS
Xpollens -->> Back : Secure payload
Back -->> SDK : Secure payload
SDK -->> SDK: JWE decryption with the private key
SDK -->> Front: Display pin

Example

---

Card display: pan, cvv and expiry date

👍

The card display can be tested in all environments, whether the environment is mocked or not.

However, on mocked environments, the response is mocked and will always return the same value.

Card Display flow chart for Android

sequenceDiagram
autoNumber
Participant Back as Partner_BackEnd 
Participant Front as  Partner_FrontEnd 
Participant SDK as SCA.Provider.SDK 
Participant Xpollens
Front ->> SDK: Client authentication
SDK ->> SDK : JWS generated with the SDK private key
SDK -->> Front: JWS
Front -->> Back: JWS
Back -->> Xpollens: Card display <br/> The proof of authentication should be transmitted in the header (cf. below)
Xpollens ->> Xpollens: JWE generated and encrypted with the public key extracted from JWS
Xpollens -->> Back : Secure payload
Back -->> SDK : Secure payload
SDK -->> SDK: JWE decryption with the private key
SDK -->> Front: Display PAN, CVV, Expiry date

🔗POST /api/sca/normal/v2.0/holderExternalRef/carddisplay/cardExternalRef

Card Display flow chart for iOS

sequenceDiagram
autoNumber
Participant Back as Partner_BackEnd 
Participant Front as  Partner_FrontEnd 
Participant SDK as SCA.Provider.SDK 
Participant Xpollens
Front ->> SDk : Wallet.getSecureDisplayCertificat
SDK ->> Front: SDK private key
Front ->> Back: SDK private key
Front ->> SDK: Client authentication
SDK ->> SDK : JWS generated with the SDK private key
SDK -->> Front: JWS
Front -->> Back: JWS
Back -->> Xpollens: Card display with JWS and private key in the headers <br/> The proof of authentication should be transmitted in the header (cf. below)
Xpollens ->> Xpollens: JWE generated and encrypted with the public key extracted from JWS
Xpollens -->> Back : Secure payload
Back -->> SDK : Secure payload
SDK -->> SDK: JWE decryption with the private key
SDK -->> Front: Display PAN, CVV, Expiry Date

Secure Display – Pin Display

Pre-requisites :

• Get the « offline_authentication_token » through the SDK
• Card status should be ‘sent’ or ‘Activated’

Inputs

Ouput

Example

---

NFC

👍

NFC is activated or deactivated when the card is created, as this feature is configured when the environment is created.

Note that in one environment, there cannot be cards with NFC, and others without. The endpoint 🔗 GET /api/v3.0/cards/cardId shows the parameter value for each card.

---

How to test

decode offline_authtentication_token

This website can be used: 🔗jwt.io

How to test pin / card display

coming soon

---

FAQ

FAQ1: After 3 consecutive wrong pin codes, what happens?

No information is sent: the card status remains activated. The only way to find out: you will receive 3 authorisation callbacks refused with a rejectedReason 117 "pin failed", the following will also be refused with a code 106 "PinBlocked". If you want to warn the enduser proactively beforehand as soon as the card is blocked, you need to take charge of development on your side.

If your 3 false pin codes are made on payments, then your chip is blocked. In this case, you can't unblock the card, so you need to order another one.

If at least one of your false pin codes is made on an ATM, then the card is blocked on the server for 7 days. It can be unblocked after 7 days by making a withdrawal with the correct pin code.

FAQ2: How long does the information pin/pan-cvv-expirydate stay on display?

As this information is confidential, it should only be displayed for a few seconds. Unfortunately, The SCA provider solution does not support this feature.