Remind current PIN of the card
The API allows a PIN reminder to be requested for a card, identified by the Issuer Card External Reference or the Card Reference when a cardholder forgot its PIN.
The card must be in “ACTIVE” status.
As a result, a PIN mailer order is generated.
API links
POST /api/v2/issuers/{issuerId}/cards/{cardReference}/remind-pin
POST /api/v2/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/remind-pin
Request data:
{
"sendingMode":"Normal",
"deliveryType":"CUSTOMER"
}Response data:
{
"responseMetadata":{
"correlationId":"2b54aa5c-aaf7-4b93-b6b2-5e12b92fa16b",
"statusMessage":"Executed successfully",
"statusCode":200,
"responseDateTime":"2023-01-03T15:14:13.531+0100",
"timeTakenMs":206
},
"data":{
"orderIdentifier":{
"orderReference":"202301032000000000389047"
},
"currentInternalStatus":"ORDERABLE",
"orderType":"PinMailerOrder"
}
}
Retrieve Card
This API enables card information for a given card identifier to be retrieved.
The response can also be enriched (if specified as embedded fields in input) with additional data such as the status history of the card, the card Contract information, the card order identifiers linked to the card.
API links
GET /api/v2/issuers/{issuerId}/cards/{cardReference}
GET /api/v2/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}
Below an example of request for
- The issuer: 1234
- Card reference: 2000000000386135
POST /api/v2/issuers/1234/cards/2000000000386135
Response data:
{
"data":{
"issuerId":"1234",
"cardIdentifier":{
"cardReference":"2000000000386135",
"issuerCardExternalReference":"EXTREF_CARD_REF_MCI_ABC_CNT_235644290"
},
"pan":"5212137209162844",
"maskedPan":"521213******2844",
"expiryDate":"1227",
"panSequenceNumber":"1",
"status":"ACTIVE",
"statusDate":"2022-12-22T11:18:11.973+00:00",
"embossingName":"REMY NAME",
"artwork":"12340001",
"permanentlyBlocked":false,
"emergencyCard":false,
"emergencyCashAdvance":false,
"renewed":false,
"replaced":false,
"cardContractIdentifier":{
"cardContractReference":"12342000000000386134",
"issuerCardContractExternalReference":"EXTREF_CARD_CRT_REF_MCI_ABC_CNT_235644290"
},
"isCardDigitalizationAllowed":false,
"panReference":"2011231c953ee52147efb5a43d532c8fa43f",
"cardScheme":"MASTERCARD",
"virtual":false,
"techAndAppModelName":"M_1234_APPTEC_MCI",
"contractType":"CONSUMER"
}
}Search card with PAN, PAN sequence number and expiry date
This API enables card information to be retrieved based on PAN or PAN reference, and optionally on PAN sequence number and/or expiry date information as search criteria.
The response can be enriched (if specified as embedded fields in input) with additional data such as the status history of the card, the card Contract information, the card order identifiers linked to the card, card identifiers of the new card in case of replacement or renewal.
API links
Below an example of request with the response
- Issuer: 1234
- PAN: 4546175178227826
As the expiry date and the sequence number are not in the request, the response gives all existing cards with the card number (here, 2 cards are provided)
POST /api/v2/issuers/1234/cards/search
Request data:
{
"pan":"4546175178227826"
}Response data:
{
"responseMetadata":{
"correlationId":"a65a1fdb-dd67-4535-9b62-a62a4efc5c3f",
"statusMessage":"Executed successfully",
"statusCode":200,
"responseDateTime":"2023-01-03T15:44:43.195+0100",
"timeTakenMs":34
},
"data":[
{
"issuerId":"1234",
"cardIdentifier":{
"cardReference":"2000000000364034"
},
"pan":"4546175178227826",
"maskedPan":"454617******7826",
"expiryDate":"1127",
"panSequenceNumber":"2",
"status":"ACTIVE",
"statusDate":"2022-11-23T13:14:44.818+00:00",
"embossingName":"Boris PAVLOV",
"artwork":"DebitClassic",
"permanentlyBlocked":false,
"emergencyCard":false,
"emergencyCashAdvance":false,
"renewed":false,
"replaced":false,
"cardContractIdentifier":{
"cardContractReference":"12342000000000364012",
"issuerCardContractExternalReference":"EXTREF_CARD_CRT_REF_VIS_ING_CNT_20221123145502"
},
"isCardDigitalizationAllowed":false,
"panReference":"1500df38371f4b2541edad420044e1ba67ba",
"cardScheme":"VISA",
"virtual":false,
"techAndAppModelName":"M_1234_APPTEC_EMVT0VISA",
"contractType":"CONSUMER"
},
{
"issuerId":"1234",
"cardIdentifier":{
"cardReference":"2000000000364013",
"issuerCardExternalReference":"EXTREF_CARD_REF_VIS_ING_CNT_20221123145502"
},
"pan":"4546175178227826",
"maskedPan":"454617******7826",
"expiryDate":"1127",
"panSequenceNumber":"1",
"status":"ACTIVE",
"statusDate":"2022-11-23T12:55:04.256+00:00",
"embossingName":"REMYPAVLOV",
"artwork":"DebitClassic",
"permanentlyBlocked":false,
"emergencyCard":false,
"emergencyCashAdvance":false,
"renewed":false,
"replaced":true,
"replacementReason":"CARD_DATA_UPDATE",
"cardContractIdentifier":{
"cardContractReference":"12342000000000364012",
"issuerCardContractExternalReference":"EXTREF_CARD_CRT_REF_VIS_ING_CNT_20221123145502"
},
"isCardDigitalizationAllowed":false,
"panReference":"1500df38371f4b2541edad420044e1ba67ba",
"cardScheme":"VISA",
"virtual":false,
"techAndAppModelName":"M_1234_APPTEC_EMVT0VISA",
"contractType":"CONSUMER"
}
]
}Retrieve Card Contract for a Card
The API enables the card contract information related to a given card to be retrieved.
The main input fields are:
- The issuer ID
- The card for which the detail is requested: It can be provided by using the card reference or the issuer card external reference.
It is also possible to request some additional data by using the embedded fields (such as the list of models linked to the card contract, the account identifiers linked to the card contract, the identifiers and the information of the linked cards).
In return, the interface provides the generic information (mainly master data) relevant to the card contract.
API links
GET /api/v2/issuers/{issuerId}/cards/{cardReference}/card-contract
GET /api/v2/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/card-contract
Below is an example of the request and the response
In input:
- The issuer 1234
- The card contract reference : 12342000000000242108
GET /api/v2/issuers/1234/card-contracts/12342000000000242108
Response data:
"data":{
"issuerId":"1234",
"cardContractIdentifier":{
"cardContractReference":"12342000000000242108",
"issuerCardContractExternalReference":"T_1234_CARD_VISA_DEBIT_CLASSIC_SHARE"
},
"cardTemplateReference":"T_1234_CARD_VISA_DEBIT_CLASSIC_SHARE",
"cardTypeCode":"F",
"status":"ACTIVE",
"openingDate":"2022-06-14T12:54:58.930+00:00",
"activationDate":"2022-06-14T12:54:58.930+00:00",
"trustedAuthenticationReference":"123420220614145458365",
"newCardRenewalAllowed":true,
"issuerBranchCode":"NO_BRANCH",
"artwork":"DebitClassicShare",
"forcedEmbossingName":"ROSINETTE F CANAILLETTE",
"schemeDeclarationOptOut":true,
"principalSupplementaryCardIndicator":"PRINCIPAL",
"productCategory":"DEBIT",
"productCategoryLabel":"IMMEDIATE_DEBIT_DEBIT",
"specificFields":{
"cardContractKey2":"value2",
"cardContractKey1":"value1"
},
"productIdentifier":{
"issuerProductExternalReference":"PDT_1234_VISA_DEBIT_CLASSIC_SHARE",
"productReference":"PDT_1234_VISA_DEBIT_CLASSIC_SHARE"
},
"cardHolderIdentifier":{
"customerReference":"CUS10000243078"
},
"contractIdentifier":{
"contractReference":"REF_MCI_BSW_CNT_216566294",
"issuerContractExternalReference":"LEGACY_REF_MCI_BSW_CNT_216566294"
},
"cardProfileDescription":"P_1234_CARD_VISA_DEBIT_CLASSIC_SHARE",
"cardProfileReference":"P_1234_CARD_VISA_DEBIT_CLASSIC_SHARE"
}Retrieve Card event list
The API enables the events information related to a given card to be retrieved (e.g. status change such as card blocking/card activation, card issuing for replacement or renewal, PIN change.)
API links
GET /api/v2/issuers/{issuerId}/cards/{cardReference}/card-events
GET /api/v2/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/card-events
Below is an example of the request and the response for:
- The issuer 1234
- The card reference : 2000000000374460
Following event types are then returned : CardBlocking, CardOrderIssuing, CardActivation, CardIssuing
GET /api/v2/issuers/1234/cards/2000000000374460/card-events
Response data:
{
"data":[
{
"eventType":"CardBlocking",
"eventDate":"2022-12-05T16:16:19.514+00:00",
"reason":"LOST",
"waiveFee":false,
"blockingInformation":{
"cardBlockingDateTime":"2022-12-05T16:16:19.514+00:00",
"blockAgent":"admin",
"blockingReason":"LOST",
"blockingReasonDetail":"LOST",
"lostStolenDate":"2022-10-11T11:14:08.493+00:00",
"lossPlace":"lossPlace",
"lossCountry":"lossCountry",
"lastUsageDate":"2022-10-11T11:14:08.493+00:00",
"lastUsagePlace":"lastUsage",
"lossCircumstances":"lossCircumstances",
"lossReportedBy":"lossReportedBy",
"lossReportedVia":"lossReportedVia",
"fraudCode":"01",
"contactData":"contactData",
"pinCompromised":true,
"customerRequestingBlockDate":"2022-10-14T08:14:08.493+00:00",
"transferEffectiveDate":"2022-10-14T08:14:08.493+00:00",
"noReplacementReason":"tempAddr",
"comment":"comment",
"cppFlag":false,
"scheduledCardBlockingReason":"LOST"
}
},
{
"eventType":"CardOrderIssuing",
"eventDate":"2022-12-05T13:13:43.385+00:00",
"waiveFee":false
},
{
"eventType":"CardActivation",
"eventDate":"2022-12-05T13:13:43.288+00:00",
"reason":"CARD_CREATION",
"waiveFee":false
},
{
"eventType":"CardIssuing",
"eventDate":"2022-12-05T13:13:43.185+00:00",
"waiveFee":false
}
]
}Retrieve blocking information for a card
The API enables the blocking information related to a given card to be retrieved.
As a response, a set of information is returned such as :
- Blocking reason and blocking date time
- The date when our system receives the blocking instruction
- If the PIN has been compromised
- Additional information in case blocking reason is LOST : Lost date, Loss circumstances, the place or the country where the card has been lost
- If a permanent card blocking is scheduled in the future
- If the card has been compromised in Common Point of Purchase (card is in CPP list)
API links
Below an example of request and the response for:
- Issuer: 1234
- Card reference: 2000000000374460
GET /api/v2/issuers/1234/cards/2000000000374460/blocking-information
Response data:
{
"data":{
"cardBlockingDateTime":"2022-12-05T16:16:19.514+00:00",
"blockAgent":"admin",
"blockingReason":"LOST",
"blockingReasonDetail":"LOST",
"lossPlace":"lossPlace",
"lossCountry":"lossCountry",
"lastUsageDate":"2022-10-11T11:14:08.493+00:00",
"lastUsagePlace":"lastUsage",
"lossCircumstances":"lossCircumstances",
"lossReportedBy":"lossReportedBy",
"lossReportedVia":"lossReportedVia",
"fraudCode":"01",
"contactData":"contactData",
"customerRequestingBlockDate":"2022-10-14T08:14:08.493+00:00",
"transferEffectiveDate":"2022-10-14T08:14:08.493+00:00",
"noReplacementReason":"tempAddr",
"cppFlag":false
}
}Update blocking information for a card
This API is no more maintained. The block card API must be used instead.
The API enables blocking information related to a given card to be updated such as:
- Blocking reason among those available for the issuer
- Blocking detail
- Lost and stolen date if the blocking reason is LOST or STOLEN
- The fraud process
- The flag indicating whether the card is in a CPP list
- The flag indicating whether the PIN is compromised
- Scheduled blocking information : delay or blocking reason if the delay is not yet reached
API links
Below an example of request for
- Issuer: 1234
- Card reference: 2000000000444867
/api/v2/issuers/1234/cards/2000000000444867/blocking-information
Request data:
{
"cppFlag":true,
"blockingReason":"LOST",
"blockingReasonDetail":"Detail blk rsn",
"lostStolenDate":"2023-03-06T17:18:42.806Z",
"pinCompromised":true,
"transferEffectiveDate":"2023-03-06T17:18:42.806Z",
"comment":"fieldComment"
}Response data:
{
"responseMetadata":{
"correlationId":"492efcae-cc01-48e0-b5b4-8944ee5937ba",
"statusMessage":"Executed successfully",
"statusCode":200,
"responseDateTime":"2023-03-06T18:26:22.009+0100",
"timeTakenMs":70
},
"data":{
"cardIdentifier":{
"cardReference":"2000000000444867",
"issuerCardExternalReference":"CARD-2023022800001A"
}
}
}Update blocking information for all cards with same PAN or same PAN reference
This API is no more maintained. The block all cards API must be used instead.
The API is similar to “Update blocking information for a card” API but is applied to all cards having the same PAN or same PAN reference.
- Blocking information can be updated such as:
- Blocking reason among those available for the issuer
- Blocking detail
- Lost and stolen date if the blocking reason is LOST or STOLEN
- The fraud process
- The flag indicating whether the card is in a CPP list
- The flag indicating whether the PIN is compromised
- Scheduled blocking information : delay or blocking reason if the delay is not yet reached
In response, card information for each matched card is provided.
API links
Create emergency card
Emergency Card is a type of card that can be provided to a customer in emergency cases (for example, a customer has lost his card, while travelling outside his country and urgently needs a new card). The customer will call 24-hour service and request an Emergency Card.
In general, those cards will have short validity period and will not be renewed and replaced. Emergency Card is not produced by the issuer but by the scheme.
The emergency card creation is possible in our system only if an Emergency Card product is defined for the issuer and if the contract of the customer is allowed to issue an Emergency Card.
The API allows to create an emergency card for a given card.
API links
Create new TAN
For PIN self-selection without a direct bank connection to the card issuing institute - i.e., without online banking access - Worldline offers the variant PIN change with TAN (Trusted Authentication Number). This applies to card programs where the bank is the card issuer for another partner, e.g., TUI or eBay.
The API allows to generate a TAN, which is used as a one-time password, printed and sent to cardholder in order to change card pin by e.g. IVR.
API links
POST /api/v2/issuers/{issuerId}/cards/{cardReference}/new-tan
POST /api/v2/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/new-tan
Below an example of request and the response for:
- Issuer: 1234
- Card reference: 2000000000410108
POST /api/v2/issuers/1234/cards/2000000000410108/new-tan
Request data:
{
"tanOrigin":"string",
"sendingMode":"normal",
"waiveFee":false,
"waiveShippingFee":false
}Response data:
{
"responseMetadata":{
"correlationId":"a3e4fb90-72f9-4154-93d1-a0050b28c273",
"statusMessage":"Executed successfully",
"statusCode":200,
"responseDateTime":"2023-01-31T15:22:50.893+0100",
"timeTakenMs":155
},
"data":{
"orderIdentifier":{
"orderReference":"202301312000000000418220"
},
"currentInternalStatus":"ORDERABLE"
}"orderType":"TanMailerOrder"
}Retrieve CVV
This service offers the option to the issuer to display the CVV2 inside the mobile app.
As the CVV2 is not stored it must be re-created using the received card data from the request.
Note: Worldline will send the encrypted CVV2 towards the issuer. The issuer is responsible for displaying the CVV2 inside the mobile app or Homebanking service.
API links
Display Pin for a card
This service offers the option to the issuer to display the PIN inside the mobile app for a given card. The card is identified either by the internal or external card reference.
Note: Worldline will only send the PIN block towards the issuer. The issuer is responsible for displaying the PIN inside the mobile app or Homebanking device.
API links
Set a Pin for a card
This Service allows the issuer to set the PIN after card creation, via issuer home banking or mobile app The card is identified either by the internal or external card reference.
API links
Reorder new Pin for a card
The API allows to order a new PIN for the card when a cardholder wants to change its PIN. The card must be in "CREATED" or "ACTIVE" status. As a result, a PIN mailer order with PIN REORDER reason is generated. This functionality can be used only if configured for the issuer.
API links
POST /api/v2/issuers/{issuerId}/cards/{cardReference}/pin
POST /api/v2/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/pin
Below an example of request for the
- Card reference: 2000000000259979
- Issuer: 1234
POST /api/v2/issuers/1234/cards/2000000000259979/reorder-pin
Request data:
{
"sendingMode":"Normal",
"deliveryType":"CUSTOMER"
}Response data:
{
"responseMetadata":{
"correlationId":"be841b98-4624-4df6-9a67-c07b0fd44cf6",
"statusMessage":"Executed successfully",
"statusCode":200,
"responseDateTime":"2023-02-03T18:52:35.578+0100",
"timeTakenMs":475
},
"data":{
"orderIdentifier":{
"orderReference":"202302032000000000327150"
},
"currentInternalStatus":"ORDERABLE",
"orderType":"PinMailerOrder"
}
}List orders for a card
The API enables the orders information related to a given card to be retrieved. The response can also be enriched (if specified as embedded fields in input) with additional data such as the orders status history of the card, the card information.
API links
GET /api/v2/issuers/{issuerId}/cards/{cardReference}/orders
GET /api/v2/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/orders
Below an example of request for the
Below is an example of the request and the response
In input:
- The issuer 1234
- The card reference : 2000000000242109
In response, one card order is provided back with the order reason (“FIRST_PIN_CARD_ISSUE”), the order date, the status, the pass-through data (“specific fields”) sent to the card embosser.
GET /api/v2/issuers/1234/cards/2000000000242109/orders
Response data:
{
"data":[
{
"issuerId":"1234",
"orderType":"CardOrder",
"orderIdentifier":{
"orderReference":"202206142000000000242110"
},
"currentInternalStatus":"ORDERED",
"currentInternalStatusDate":"2022-06-14T12:57:19.090+00:00",
"sendingMode":"Normal",
"deliveryType":"CUSTOMER",
"orderReason":"FIRST_PIN_CARD_ISSUE",
"cardProducer":"00022",
"specificFields":{
"insuranceCode":"insuranceCode",
"cardOrderKey2":"value2",
"cardOrderKey1":"value1"
},
"cardIdentifier":{
"cardReference":"2000000000242109"
},
"free":true
}
]
}Retrieve card order for a card
The API enables the order information (card, PIN mailer or TAN mailer order) related to a given card to be retrieved. The order is identified with order reference.
The response can also be enriched (if specified as embedded fields in input) with additional data such as the orders status history of the card, the card information.
API links
GET /api/v2/issuers/{issuerId}/cards/{cardReference}/orders
GET /api/v2/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/orders
Below is an example of the request and the response
In input:
- The issuer 1234
- The card reference : 2000000000242109
- The card order reference: 202206142000000000242110
GET /api/v2/issuers/1234/cards/2000000000242109/orders/202206142000000000242110
Request data:
{
"sendingMode":"Normal",
"deliveryType":"CUSTOMER"
}Response data:
{
"data":{
"issuerId":"1234",
"orderType":"CardOrder",
"orderIdentifier":{
"orderReference":"202206142000000000242110"
},
"currentInternalStatus":"ORDERED",
"currentInternalStatusDate":"2022-06-14T12:57:19.090+00:00",
"sendingMode":"Normal",
"deliveryType":"CUSTOMER",
"orderReason":"FIRST_PIN_CARD_ISSUE",
"cardProducer":"00022",
"specificFields":{
"insuranceCode":"insuranceCode",
"cardOrderKey2":"value2",
"cardOrderKey1":"value1"
},
"cardIdentifier":{
"cardReference":"2000000000242109"
},
"free":true
}
}Reset Pin try counter for a card
This API enables the issuer to reset the PIN try Counter value.
A control related to this counter value ((MAX Pin try) can be performed during the authorization processing if configured.
API links
Advice a product extension for a card
This API is used to get the product extension for a card replacement depending on the configured algorithm.
The main input fields are:
- The issuer ID
- The card for which the advice is requested: It can be provided by using the card reference or the issuer card external reference.
The API returns the product extension advised for the card replacement and also the current product extension of the card.
API links
Get parameters for a letter template
The API allows to retrieve the prefilled parameters of a letter template for a card.
The main input fields are:
- The issuer ID
- The card for which the template parameters are requested: It can be provided by using the card reference or the issuer external card reference
- The letter template reference
As a result, the list of the letter template parameter names with the default values assigned to them, are returned, which can be used to prefill the letter template with default values.
API links
List of available letter templates for cards
The API allows to retrieve the list of available letter templates for an Issuer related to the cards. The main input fields are:
The main input fields are:
- The issuer ID
If requested, the API allows also to request to enrich the response with additional data relative to the template parameters by using embedded fields.
In return, the interface provides the list of available letter templates for the requested issuer with the related parameters if requested.
API links
Retrieve a specific letter template
The API allows to retrieve a specific letter template by its reference.
The main input fields are:
- The issuer ID
- The letter template reference for which its details is requested
If requested, the API allows also to request to enrich the response with additional data relative to the template parameters by using embedded fields.
In return, the interface provides letter template information with the related parameters if requested.
API links
Retrieve letter for a card
The API allows to retrieve a specific letter for a card.
The main input fields are:
- The issuer ID
- The card for which the letter is requested: It can be provided by using the card reference or the issuer external card reference
- The letter reference by providing the letterId
In return, the interface provides letter information for the requested card. Deleted letters are not returned by this interface.
API links
Generate a letter for a card
The API allows to generate a letter for a card.
The main input fields are:
- The issuer ID
- The card for which the letter generation is requested: It can be provided by using the card reference or the issuer external card reference
- The letter template reference which is used to generate the letter
During letter generation following controls will be performed:
- If the template parameter is defined with a validator, the validator will be applied on the provided value.
- If the template parameter is a list (display type = list), the system will check that the provided value belongs to the list.
- If the template parameter is not modifiable, the system will check that the provided value is equal to dynamically computed value.
- If the value is defined as invalid, the system will check that the provided value is not equal to dynamically computed value.
- If the template is configured with a validator (xsd file for instance), the validator will be applied on the generated letter.
- If the value is not provided in input, the value dynamically computed by the system will be used.
API links
Validate a letter for a card
The API allows to validate a letter for a card.
The validation status of the letter must be VALIDATION_NEEDED.
The main input fields requested by the API are:
- The issuer ID
- The card for which the letter validation is requested: It can be provided by using the card reference or the issuer external card reference
- The letter reference by providing the letterId
As a result, the validation status of the letter is changed to VALIDATED.
API links
Delete a letter for a card
The API allows to delete a letter for a card.
The main input fields requested by the API are:
- The issuer ID
- The card for which the letter deletion is requested: It can be provided by using the card reference or the issuer external card reference
- The letter reference by providing the letterId
The following controls will be performed during letter deletion:
- If a cut off hour is configured the deletion is allowed if the generation and deletion occurs during the same 24 hour period between one cut-off time and the next cut off time
- if no cut off hour is configured then the letter can be deleted only on the same day it was generated
API links