Skip to main content

Cards Issuing

This document applies for Physical and Vitual cards Order .


The prerequisites to call this endpoint are:

  • Client Authentication.
  • Offer partner code.
  • Cardholder existence.
  • Account existence.

Diagram & statuses

Order a card: sequence diagram for production and unmocked environment

Physical card order process (Ramdom PIN)

Physical card order process ( Wishpin )

⚠ If you are using the wishpin, you have 4 days to send the pin associated to your card.
Otherwise, the card order will fail at BPCE PS, and a callback 21 is received with the status "5" (failed).

Virtual card order process

⚠ Note: no callback 21 is sent when the virtual card is issued.
The synchronous response has to be treated immediatly.

Order a card: sequence diagram for mocked environment

In mocked environment, card oredering is mocked. As a consequence:

  • card status changes immediately from ordered to sent
  • callback 21 for creation is immediately received

Physical card order process (Applies to Random PIN and Wish PIN)

For virtual card, the sequence diagram remains the same.

Virtual card order process

States diagram for physical cards

Deactivated for remanufacturing

States diagram for virtual cards

Wishpin process


The WishPIN Xpollens solution complies with the new BPCE security standards.

Solution relies on

  • the tokensignature API see here
  • an SDK provided by Thales

SDK and SDK documentation are available to download here (Files are password protected, please ask access through our support team) :

SDK & Documentation
SDK Documentation
CardCompanion SDK - Technical documentation -

Functional principle is as follows :

  • To define his/her PIN, the user first create its card by specifying wishPIN is needed (haswishpin:true).
  • The card’s creation returns a card reference (cardExternalRef or AppCardId).
  • This reference should be passed to the signature service and finally to the WishPIN SDK along with the signature.
  • The defined PIN is then sent in real time to Thales through the SDK and then sent from Thales to BPCE/PS.
  • Card order and WishPIN are then reconciled then the card is sent for customization.

The PIN code entered by the end user in the partner mobile application is sent in real time to the Thales PIN definition platform. PIN codes are stored cyphered on the platform then sent by batch on a daily basis to BPCE to reconciliate Cards and PIN

4 days max after which the WISHPIN request is rejected the reconciliation is not possible

API Signature
Partner authentication toward PIN processor will be done against a BPCEPS/HSM token and then sent with the corresponding signature by the SDK.

Order the card with wishpin

The first step required to set up a card with user-selected PIN is to order the card, specifying the use of the wishPIN in the API call.

Example POST /api/v3.0/cards

"cardId": "{{cardExternalRef}}",
"cardholderId": "{{appUserId}}",
"accountId": "{{accountId}}",
"offerPartnerCode": "{{cardOffer}}",
"hasWishpin": true,
"isNfcDisabled": false,
"visualCode": "{{cardVisual}}"


"cardExternalRef": "06ae7f8f02",
"partnerCode": "xpo-bling-sb-mock-001"

A callback 21 will be send to the partner after the card order has been received by the processor (BPCE PS).

Get the tokensignature

Once the card order has been performed, it is mandatory to retrieve some secure card token information that will be shared with Thales through the provided SDK so that it can handle the PIN request.

For this, the GET api/v2.0/tokensignature/{{cardExternalRef}} has to be called by the partner.

Example GET api/v2.0/tokensignature/{{cardExternalRef}}


"certificate_alias": "",
"token_signature": "{{tokensignature}}",
"card_unique_id": "1652800161toJDcN2SIkChUg1yc9ZEiQ",
"transaction_id": "efe4a0303caf4e868392e8652e929d81",
"transaction_timespan": "1702994478"

Information returned by the tokensignature API will have be passed to the Thales SDK.

Thales SDK

Chapter 5.6.1 and 6.4 of the SDK documentation describes the format of the expected fields used to build the input JSON token to the definePINToken method of the SDK.

definePINToken method (§5.6.1)

contextContextThe Android application context
hostURLStringThe back-end URL from Digital PIN solution provided by the project manager
tokenStringThe token is a message in JSON format containing information relative to the bank and cardholder.
Token in JSON format as described in the section:
§6.4 Token and Signature
signatureStringThe signature computed over the token for verification.
Generation is explained in the following section of the document:
§6.4 Token and Signature
pinValueStringPIN in clear format (e.g. 1234)

HostURL for test/sandbox environment :
HostURL for production environment :

token format (§6.4)

Token Format
Token is used in PIN Distribution and PIN Definition schemes to provide information about the cardholder and the request.

The token shall comply with this format:

"IdBEL": "IdBEL",
"IdFournisseur": "IdFournisseur",
"IdPorteur": "IdPorteur",
"IdTransaction": "IdTransaction",
"SignatureCertAlias": "SignatureCertAlias",
"Timestamp": "Timestamp",
"Type": "Type"

Besides, the token MUST NOT be modified at all after it is signed. Otherwise, the signature verification may fail. The token shall only be composed with alphanumeric characters: [a-zA-Z0-9].

⬛ Token and Signature CB compliant
The token must be formatted as a JSON message and needs to contain the following information:

  • IdBEL: Customer unique Identifier.
  • IdFournisseur: Unique identifier of the service provider used during authentication.
  • IdPorteur: Unique ID (uid) of the cardholder retrieving his PIN. Same unique id used during provisioning step.
  • IdTransaction: Unique identifier of the transaction. All request following will be rejected if they use the same idTransaction.
  • Timestamp: Timestamp in UNIX format (unit second) generated for each transaction.
  • Type: Transaction type: Only 02 is used and supported in Xpollens context for PIN definition
  • SignatureCertAlias: alias of the certificate used to sign the token – Optional –

tokensignature and token mapping

The information retrieved from the tokensignature API have to be mapped to the expected JSON token used in definePINToken SDK method.

The mapping table is as follow :

tokensignaturedefinePINToken parameterExample ValueDescription
N/AIdBEL30007Customer unique Identifier (XPollens/Fixed Value)
card_unique_idIdPorteur1652800161toJDcN2SIkChUg1yc9ZEiQXPollens Card Id shared with
Thales and BPCE
transaction_idIdTransactionefe4a0303caf4e868392e8652e929d81XPollens issued wishPIN transaction id
certificate_aliasSignatureCertAliasnatixis.devalias/identifier of used certificate to cypher the PIN for test/sandbox environment for production environment
transaction_timespanTimestamp1702994478XPollens issued WishPIN request timestamp
N/AType02Constant : 02 for PIN definition

Calling the definePINToken SDK method

Once the token is built from the information returned by tokensignature API. The definePINToken has to be called in the partner application.

Note The definePINToken call shall not be initiated from the main UI thread but from its own thread.

Example : Android simple implementation

button.setOnClickListener {
val hostUrl: String = ""
var token: String = "\"IdBEL\":\"30007\",\"IdPorteur\":\"\${idPorteur.toString()}\",\"IdFournisseur\":\"TH\",\"IdTransaction\":\"\${idTrans.toString()}\",\"Timestamp\":\"\${timestamp.toString()}\",\"Type\":\"02\",\"SignatureCertAlias\":\"\"}"
var signature: String = "\${signature.toString()}"
val pinValue: String = "\${pin.toString()}"
val executionResponse = definePINToken(applicationContext,hostUrl, token, signature, pinValue)
var result = false
if (executionResponse.errorCode == "0") {
// The PIN was set properly for the given cardholder
result = true
} else {
// An issue occurred, handle the error code
Log.d("\[CCSDK\]", "\[DefinePin\]Response: " + executionResponse);
result = false

Configuration when creating the environment

Random pin or wishpin?

Random pin: the pin is chosen at random when the card is created. Wishpin: the enduser can choose its own pin. The enduser has 4 days to do so, otherwise the card creation fails.

If the configuration is 'Random Pin', then you have no choice but to go random pin. If the configuration is 'Wishpin', then you have the choice of the pin type when using the endpoint.

Card validity period

The card's validity period is fixed and is set when the environment is created. This information is shared with BPCE PS.

Card offers and visual codes

"cardId": "my_card_reference",
"cardholderId": "145644-060820-USER-8550478",
"accountId": "145644-060820-ACCOUNT-8550478",
"offerPartnerCode": "DemoClassicPhysicalDebitVISA",
"hasWishpin": true,
"isNfcDisabled": false,
"visualCode": "NOCP"

The card offer allows you to find out the type of card you want (classic, premier, etc.) and its characteristics. This information is an input for card creation.

For each offer, you can have several visuals. All these visuals are validated with BPCE PS and VISA and then configured at Xpollens.

Pan ranges

They are chosen by Xpollens and validated with BPCE PS.

API, Callback & technical items

Card order

POST /api/v3.0/cards

When ordering a virtual card, the wishpin and nfc attributes must be removed from the request.

SDK Thales

SDK & Documentation
SDK Documentation
CardCompanion SDK - Technical documentation -

How to test

Create a virtual card

POST /api/v3.0/cards
"cardId": "yourCardId",
"cardholderId": "yourCardHolderId",
"accountId": "yourAccountId",
"visualCode": "yourVisualCode"