Skip to main content

Card lifecycle

Welcome in the Card program management.

If you are here it is because you want to launch a card program. First of all, to create your card program management, we 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 card design simulator, the packaging and the life cycle journey.

Order a card#

First, your customer order a card. You can purpose him a standard journey with a sample order of card. But you can purpose him some different journey like wish PIN or temporary virtual card....

Order a physical card#

You can order a card using this journey 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 partner
  • visualCodeSelected : 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 issue due to mobile with incorrect time.

In addition (recommended but it's no mandatory), because Bank's compliance doesn’t allow Smartphones to send the PIN (even ciphered) 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.

Remember you have 2 choices : Random PIN (by default, no need to implement anything) or Wish PIN in order to allow to your end user to define his own PIN code. Obviously, you always have possibility to display PIN in addition.
WishPIN is only possible for mobile app. You have to add our sdk in addition with a Token signature API

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 partner
  • visualCodeSelected : 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 USED
  • isNfcActivated : NOT USED

When your end user order a virtual card, obviously there is no PIN with a virtual card. So, wishPIn and isNfcActivated is not used.
When your end user order a virtual card, he can use it instantly in e-commerce or add in a wallet xpay for point of sale.

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.

You want a physical card but you don't want or can't to wait. You order a temporary virtual card.
Obviously there is not random or wish PIN with a virtual card
You have to order a virtual card first and then use a other endpoint to materialize your virtual with the same data cards

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

When your end user opposed his card, you can just refabricate.

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)
}
DO NOT USE for an account closure because card cancellation is included in a account closure.