Card lifecycle
Welcome in the Card program management.
If you are here it's because you want to launch a card program. First of all, to create a card program management, we need to define your card product with a first filter :
- funding source : Immediate Debit, Prepaid, Deffered Debit
- for who : Consumer, Business, Corporate ...
- which product : Classic, Gold, Infinite
Then we adapt it depending on the type of card you want :
- physical or virtual card,
- token (xPay)
- wearable (keyring, bracelet..)
And at the end, we use our dedicated simulator to design the card, the packaging and the card lifecycle.
Order a card
First, your customer has to order a card. You can offer him a standard journey with a simple card subscription. You can also offer him some alternative customer journey with options like wish PIN or temporary virtual card....
Order a physical card
You can order a card using this path by example.
POST /api/v2.0/card
{
"offerPartnerCode": "string", [required]
"holderExternalRef": "string", [required]
"cardExternalRef": "string", [required] constraints: Max 50 chars
"visualCodeSelected": "string", constraints: Max 10 chars
"label": "string", constraints: Max 50 chars
"wishPin": "boolean",
"isNfcActivated": "boolean",
}
offerPartnerCode: The Partner's offer code provided by Xpollens.holderExternalRef: The user/holder's reference attributed by the partner.cardExternalRef: The card's reference attributed by the partnervisualCodeSelected: The partner can define one or several visual codes for the same offer (same product). If the attribute is not entered when ordering the card, then the visual code defined by default in the offer will be selected for the card.label: The name or partner's reference of the card.wishPin: The Partner can choose to create the card with or without wishpin (If the partner 's offer doesn't support it, then the PIN will be randomly generated). If the attribute is not entered when ordering the card, and defined by default in the offer, then the card will be created with a pin chosen by the holder.isNfcActivated: The Partner can choose to create the card with or without NFC (If its' by default deactivated in the offer, then the card will be created without NFC). If the attribute is not entered when ordering the card, and activated by default in the offer, then the NFC will be activated for the card.
Choose your PIN
In this PIN Definition scenario, a token and signature must be generated by a customer back-end and provided to wishPIN's SDK.
The signature will act as a proof of authentication.
Because the signature generation requires the use of the RSA private key it must be generated by a back-end and not inside the app.
We also recommend to generate the token in the back-end computing the signature and not in the mobile application, to avoid timestamp issues due to mobile with incorrect time.
In addition (recommended but not mandatory), because Bank's compliance doesn’t allow Smartphones to send the PIN (even secured) to the PINDefinition backend the PIN format send by the mobile must be the position in the keypad coordinates table shared by Manufacturer’s PINDefinition back-end.
Example: keypad coordinates [9,5,1,3,5,7,4,0,8,6,2] shared by back-end and PIN selected by cardholder 1234. Coordinates provided to Card Companion SDK must be 2936 – index in the table -).
SDK
More information regarding the specifications in our SDK PIN Definition.
Order a virtual card
Order a virtual uses the same API to create a card (physical or virtual). Change is your offer.
POST /api/v2.0/card
{
"offerPartnerCode*": "string", [required]
"holderExternalRef*": "string", [required]
"cardExternalRef*": "string", [required] constraints: Max 50 chars
"visualCodeSelected": "string", constraints: Max 10 chars
"label": "string", constraints: Max 50 chars
"wishPin": "boolean", always false (not used)
"isNfcActivated": "boolean", always false (not used)
}
offerPartnerCode: The Partner's offer code provided by Xpollens.holderExternalRef: The user/holder's reference attributed by the partner (holderExternalRef = appUserId).cardExternalRef: The card's reference attributed by the partnervisualCodeSelected: The partner can define one or several visual codes for the same offer (same product). If the attribute is not entered when ordering the card, then the visual code defined by default in the offer will be selected for the card.label: The name or partner's reference of the card.wishPin: NOT USEDisNfcActivated: NOT USED
Order a temporary virtual card
Two interesting use cases :
1- In subscription for waiting your physical card.
2- In emergency, you are not in your country but in holidays, you blocked your card (for stolen or lost reason) and you can order an emergency virtual card waiting your new physical card.
Manage your card
Refabricate a card
You can refabricate a card from an existing card when you cardholder has a technical problem with his card (rarely). Using this feature like an ordering card but more simply.
POST /api/v2.0/card
{
"cardExternalRef*": "string", [required]
"oldCardExternalRef*": "string", [required]
"visualCodeSelected": "string"┃null, constraints: Max 10 chars
"label": "string"┃null, constraints: Max 50 chars
}
oldCardExternalRef: It’s the reference of the previous card in the refabrication process (Card mother). (Others are the same)
RESPONSE OK/KO
Cancel a card
For specific cases, you can use a card cancellation.
PATCH /api/v2.0/card/{cardExternalRef}/cancel
{
"cardExternalRef*": "string", [required]
"cancellationReason": "string", Restricted values of cancellation reason code are :
1 The customer no longer wants his card
2 The customer left the bank
3 Deceased customer
4 Partner request
6 Other reason (default value if not provided in the input parameters)
}