The API allows the card contract details to be retrieved.

The main input fields are:

• The issuer ID
• The card contract for which the detail is requested: It can be provided by using the card contract reference or the issuer card contract external reference.

It is also possible to request some additional data by using the embedded fields.

In return, the interface provides the generic information (mainly master data) relevant to the card

API links

"data":{
   "issuerId":"1234",
   "cardContractIdentifier":{
      "cardContractReference":"12342000000000374459"
   },
   "cardTemplateReference":"T_1234_CARD_VISA_DEBIT_CLASSIC",
   "cardTypeCode":"F",
   "status":"ACTIVE",
   "openingDate":"2022-12-05T13:13:43.165+00:00",
   "activationDate":"2022-12-05T13:13:43.177+00:00",
   "trustedAuthenticationReference":"123420221205141343905",
   "newCardRenewalAllowed":true,
   "issuerBranchCode":"NO_BRANCH",
   "artwork":"DebitClassic",
   "forcedEmbossingName":"KAISHNER",
   "schemeDeclarationOptOut":false,
   "principalSupplementaryCardIndicator":"SUPPLEMENTARY",
   "productCategory":"DEBIT",
   "productCategoryLabel":"IMMEDIATE_DEBIT_DEBIT",
   "specificFields":{
      "additionalProp1":"string",
      "additionalProp3":"string",
      "additionalProp2":"string"
   },
   "productIdentifier":{
      "issuerProductExternalReference":"PDT_1234_VISA_DEBIT_CLASSIC",
      "productReference":"PDT_1234_VISA_DEBIT_CLASSIC"
   },
   "cardHolderIdentifier":{
      "customerReference":"CUS10000346489",
      "issuerCustomerExternalReference":"HOME_ADDR_REF_PERSON-202212050001B"
   },
   "contractIdentifier":{
      "contractReference":"4459f986-5242-4202-9ed5-f652573e9f63",
      "issuerContractExternalReference":"CONTRACT-202212050001"
   },
   "cardProfileDescription":"P_1234_CARD_VISA_DEBIT_CLASSIC",
   "cardProfileReference":"P_1234_CARD_VISA_DEBIT_CLASSIC"
}
}

The API allows the cardholder data linked to the card contract to be retrieved.

The main input fields are:

• The issuer ID
• The card contract for which the detail is requested: It can be provided by using the card contract reference or the issuer card contract external reference.

It is also possible to request some additional data by using the embedded fields.

In return, the interface provides the generic information of the customer.

API links

"data":{
   "issuerId":"1234",
   "customerIdentifier":{
      "customerReference":"CUS10000346489",
      "issuerCustomerExternalReference":"HOME_ADDR_REF_PERSON-202212050001B"
   },
   "active":true,
   "birthDate":"1979-02-20T00:00:00.000+00:00",
   "birthPlace":"Lorch",
   "commercialStatus":"Normal",
   "courtesyTitle":"Frau",
   "firstName":"Kristina",
   "lastName":"KAISHNER",
   "monthlySalary":"0",
   "nationality":"DE",
   "offlineRiskCategory":"Standard",
   "onlineRiskCategory":"Standard",
   "sex":"F"
}

The API allows all the cards of a card contract to be retrieved.

The main input fields are:

• The issuer ID
• The card contract for which the cards list is requested: It can be provided by using the card contract reference or the issuer card contract external reference.

In return, the interface provides the list of all the cards linked to the card contract. Each card is provided with additional information such as card status, expiry date, embossing line, blocking reason (if in blocked status).

API links

{
   "data":[
      {
         "issuerId":"1234",
         "cardIdentifier":{
            "cardReference":"2000000000374460"
         },
         "pan":"4546174862942386",
         "maskedPan":"454617******2386",
         "expiryDate":"1227",
         "panSequenceNumber":"1",
         "status":"BLOCKED",
         "statusDate":"2022-12-05T16:16:19.514+00:00",
         "embossingName":"KAISHNER",
         "artwork":"DebitClassic",
         "permanentlyBlocked":true,
         "emergencyCard":false,
         "emergencyCashAdvance":false,
         "renewed":false,
         "replaced":true,
         "replacementReason":"LOST_STOLEN",
         "blockingReason":"LOST",
         "cardContractIdentifier":{
            "cardContractReference":"12342000000000374459"
         },
         "isCardDigitalizationAllowed":false,
         "panReference":"15001defb91548a045a2a67f1f5d944a0b7e",
         "cardScheme":"VISA",
         "virtual":false,
         "techAndAppModelName":"M_1234_APPTEC_EMVT0VISA"
      },
      {
         "issuerId":"1234",
         "cardIdentifier":{
            "cardReference":"2000000000374491",
            "issuerCardExternalReference":"CARD-20221119"
         },
         "pan":"4546174672045636",
         "maskedPan":"454617******5636",
         "expiryDate":"1227",
         "panSequenceNumber":"1",
         "status":"ACTIVE",
         "statusDate":"2022-12-05T16:27:57.533+00:00",
         "embossingName":"KAISHNER",
         "artwork":"DebitClassic",
         "permanentlyBlocked":false,
         "emergencyCard":false,
         "emergencyCashAdvance":false,
         "renewed":false,
         "replaced":false,
         "cardContractIdentifier":{
            "cardContractReference":"12342000000000374459"
         },
         "isCardDigitalizationAllowed":false,
         "panReference":"1500d015027a202e47b39d56e25aab9fcc1d",
         "cardScheme":"VISA",
         "virtual":false,
         "techAndAppModelName":"M_1234_APPTEC_EMVT0VISA"
      }
   ]
}

The API allows the contract detail of a card contract to be retrieved.

The main input fields requested by the API are:

• The issuer ID
• The card contract for which the contract information is requested: It can be provided by using the card contract reference or the issuer card contract external reference.

It is also possible to request some additional data, such as contract customers, accounts, legitimacy documents, by using the embedded fields.

In return, the interface provides the contract details.

API links

{
           "data":{
              "issuerId":"1234",
              "contractIdentifier":{
                 "contractReference":"4459f986-5242-4202-9ed5-f652573e9f63",
                 "issuerContractExternalReference":"CONTRACT-202212050001"
              },
              "issuerBranchCode":"NO_BRANCH",
              "cardReleaseOrder":"AUTOMATIC",
              "signatureDate":"2022-12-05T12:34:43.000+00:00",
              "status":"SIGNED",
              "statusDate":"2022-12-05T12:34:43.000+00:00",
              "contractOwnerIdentifier":{
                 "customerReference":"CUS10000346472",
                 "issuerCustomerExternalReference":"PERSON-202212050001"
              },
              "productIdentifier":{
                 "issuerProductExternalReference":"PDT_1234_VISA_DEBIT_CLASSIC",
                 "productReference":"PDT_1234_VISA_DEBIT_CLASSIC"
              },
              "rootAccountIdentifier":{
                 "accountReference":"12346621070985963583",
                 "issuerAccountExternalReference":"ROOT_ACCOUNT-202212050001"
              }
           }
        }

The API allows a list of pre-defined parameters (attributes) of a card contract to be updated.

The main input fields are:

• The issuer ID
• The card contract for which updates are required: It can be provided by using the card contract reference or the issuer card contract external reference.
• Parameters to be updated

The card contract parameters can be retrieved using the Retrieve card Contract detail API.

The updated parameters should be consistent with the initial product configuration defined in the system (e.g., a change of model is accepted only if the provided model reference is allowed in the product definition).

A typical update for the card contract is the embossing name.

API links

{
           "forcedEmbossingName":"Kristina KAISHNER",
           "specificFields":{
              "additionalProp1":"A14587"
           }
        }

{
           "responseMetadata":{
              "correlationId":"74c91831-9f60-4f94-90eb-dffae27af2ed",
              "statusMessage":"Executed successfully",
              "statusCode":200,
              "responseDateTime":"2022-12-19T11:20:02.972+0100",
              "timeTakenMs":570
           },
           "data":{
              "cardContractIdentifier":{
                 "cardContractReference":"12342000000000374459"
              }
           }
        }

The API allows a card contract to be closed.

The main input fields are:

• The issuer ID
• The card contract for which the closure is requested: It can be provided by using the card contract reference or the issuer card contract external reference.
• The parameters of the closure: reason, delay, date.

A card contract can be either closed immediately or in the future (either at the card expiry date or at another scheduled date).

When the card is terminated (when the closing date is reached):

• The card is immediately deactivated (next authorizations are declined).
• The card cannot be renewed or replaced anymore.
• Reimbursement of membership and account setup fees is possible if applicable
• The card account cannot be closed:
  • before X days (e.g., to take into account the latest transactions)
  • if there are ongoing disputes
• Once an account is closed, any incoming scheme transaction is automatically disputed.

API links

This API enables to cancel a card contract closing with a scheduled date in the future.

As a result, no closing date is planned anymore for the card contract.

API links

The API allows the list of card contracts to be retrieved which have the same card contract group reference.

The main input fields are:

• The issuer ID
• The group reference of the card contract for which the detail is requested

It is also possible to request some additional data by using the embedded fields.

In return, the interface provides the generic information (mainly master data) relevant to the card contract.

API links

Worldline Card Issuing Processing API uses a secure authentication mechanism keeping the data and the  interaction between the issuer and Worldline secure and reliable. In order to authenticate on the API via Oauth2, you first need to get provided with a Consumer Key and Consumer Secret to retrieve by calling our Oauth2 Authentication server and then try out the APIs via the developer portal or   your app.

`curl --location --request POST 'https://issuing-solutions.eae.apis.svc.as8677.net/oauth/accesstoken' \ 
--header 'Authorization: Basic {{Consumer Key and Consumer Secret}}' \ 
--header 'Content-Type: application/x-www-form-urlencoded' \
 --data-urlencode 'grant_type=client_credentials' 

                { ... "access_token": {{access_token}}", ... }                      

Our API uses basic HTTP response codes to indicate the resulting status of each request.

• Codes in the 2xx range indicate success
• Codes in the 4xx range indicate an error
• Codes in the 5xx range indicate a server error

Our API Responses contain two separate part : 

• responseMetadata is containing technical information about the execution of the request.
• data the functional and business data.

The responseMetadata is formatted as shown hereafter and contains the following information

• correlationId : WL-Correlation-Id from the headers
• statusMessage : Message about Execution Status
• statusCode : HTTP Response Code (same than Response one)
• responseDateTime : when response is received
• timeTakenMs : elapsed ms time on server time (for 200 OK cases)

Block card – unknown card (http 404)

                {
                    "responseMetadata": {
                        "statusMessage": "UNKNOWN_CARD: Error occurred while blocking the card
                       : [2000000033334867] is null in BlockCardOutput blockCard()",
                        "statusCode": 404,
                        "responseDateTime": "2023-03-15T13:59:17.231+0100",
                        "timeTakenMs": 20
                    }
                }
                
                

Block card – bad request - invalid data request (http 400)

                {
                    "responseMetadata": {
                        "statusMessage": "INVALID_BLOCKING_REASON: Error occurred while block the card by input:  
                        [fae96f4c-1697-4b18-98ae-6b84c355776d] during 
                        BlockCardOutput blockCard() call:   [CARD_INVALID_BLOCKING_REASON]",            
                        "statusCode": 400,
                        "responseDateTime": "2023-03-15T14:02:20.446+0100",
                        "timeTakenMs": 26
                    }
                }                
                

Block card – bad request – mandatory field missing (http 400)

                {
                    "responseMetadata": {
                        "statusMessage": "REQUEST_VALIDATION_ERROR: [blockingReason - must not be null]",
                        "statusCode": 400,
                        "responseDateTime": "2023-03-15T14:04:58.955+0100",
                        "timeTakenMs": 16
                    }
                }                
                

Block card – bad request – mandatory field missing (http 400)

                            {
                            "responseMetadata": {
                            "statusMessage": "REQUEST_VALIDATION_ERROR: [blockingReason - must not be null]",
                            "statusCode": 400,
                            "responseDateTime": "2023-03-15T14:04:58.955+0100",
                            "timeTakenMs": 16
                            }
                            }
    

Block card – forbidden (http 403)

            {
            "responseMetadata": {
            "correlationId": "af5c01bc-18de-4918-98df-74af278b7849",
            "statusMessage": "The current user is not allowed to do the action! Category: 
             ISSUER, Resource: 1234, Action: access",
            "statusCode": 403,
            "responseDateTime": "2023-03-15T14:11:22.111+0100",
            "timeTakenMs": 18
            }
            }
                         
    

Worldline Card Issuing Processing API Responses contains two separate part :

  

• responseMetadata is containing technical information about the execution of the request.
• data the functional and business data.

The responseMetadata is formatted as shown hereafter and contains the following information

• correlationId : WL-Correlation-Id from the headers
• statusMessage : Message about Execution Status
• statusCode : HTTP Response Code (same than Response one)
• responseDateTime : when response is received
• timeTakenMs : elapsed ms time on server time (for 200 OK cases)

              
{
    "responseMetadata": {
        "correlationId": "8f7cb0d5-3f5b-4935-bc10-e2c45b46b5df",
        "statusMessage": "Executed successfully",
        "statusCode": 200,
        "responseDateTime": "2021-10-13T15:59:50.302+0200",
        "timeTakenMs": 129
    },
    "data": {
        ...
    }
}                   

Each API request has an associated correlation identifier. This correlation identifier can be found metadata information and in WL-Correlation-ID  Request headers. This correlation identifier can be set in WL-Correlation-ID Request headers and is used to provide support about a specific request. If not provided, it's generated by Worldline system as an UUID.

All of the APIs that could return a huge list of resources are supporting pagination using the page and offset parameters in the request formatted on with the following way : ?page={{page}}&offset={{offset}}

{{baseUrl}}/issuers/{{issuerId}}/accounts/{{accountReference}}/operations?page=5

{{baseUrl}}/issuers/{{issuerId}}/accounts/{{accountReference}}/operations?page=5&offset=100  

Some of the fields can be expanded in order to retrieve additional information when retrieving the detail of one resource within the same request by using the embed request parameter. Multiple fields can be provided and should be separated by a comma (,). By default fields that can be expanded are not provided in the response

{{baseUrl}}/issuers/{{issuerId}}/cards/{{cardReference}}?embed=cardContract

In order to retrieve only the attributes that are relevant in the response of the APIs, the filter parameter can be used in the request. The name of the fields to be retrieved should be provided and you can filter recursively by specifying nested fields after a dot(.). Multiple fields can be provided and should be separated by a comma (,)

{{baseUrl}}/issuers/{{issuerId}}/contracts/create-consumer-contract?filter=contract.contractIdentifier,contract.cardContracts.card.cardIdentifier 

The major versions of the Wordline Card Issuing Processing APIs are distinguished by the version indicator in the URLs (currently the V2 /api/v2/ ). Minor version updates will not result in a new version indicator in the API URLs. All minor updates are considered to be backwards compatible. Only when changes are not backwards compatible, will we issue a new major version of the API.

The data model used in our system is represented as follows :

The different resources are identified by corresponding references.

References can be internal, which means generated by our system and transmitted to the issuer.

Wordline supports also the usage of external references that means the bank provides us the value; this implies that the generation of this identifier follows rules shared by Wordline (unicity of the reference).

External references must be provided generally during the resource generation such as for:

• External contract reference during contract creation
• External card reference during card creation
• External account reference during account creation

Please find below a table illustrating the resources for which external reference is allowed.

Products are organized in a product catalogue. A product is a set of parameters and features that define the behaviour and functionalities of a set of Cards and Accounts.

Models and template concepts

The configuration of the product is performed by Worldline, based on Issuer requirements, through the definition of cards and accounts templates.

The first step of product configuration is the definition of models.

A model defines the possible behaviour for a product (general parameters grouped by rules and functions); several models belonging to the same type can be defined for a product.

There are card models and account models:

• Card models
  • Card creation model
  • Replacement model
  • Card event fee model
  • …
• Account models
  • Restriction model
  • Transaction fee model,
  • Markup fee model
  • Amount due model
  • …

A template is composed of models and defines the default values of the product by selecting one model per model type. The other models defined in the product can be then used later for customization.

The below diagram provides an overview of the configuration linked to the Issuer and the product. It illustrates especially:

• the possible models for card and account
• the parameters linked to an issuer

“Pass-through data” correspond to data provided by the issuer in the APIs and transmitted without business process to an external system by Worldline card issuing solution.

This can be typically data requested by the embosser and transmitted directly by the issuer (e.g.: photo reference ID, …).

Pass-through data are identified in the API fields “specificFields”.

The data must be provided with the following format: labelname:value separated by a “|” character.

The fields can be attached to a contract, a card, an account, a card contract, a card order, a PIN/TAN mailer, or a customer.

The standard contract lifecycle applied on Worldline Card Issuing reflects the relation between you (as an “Issuer”) and an individual cardholder (retail market) or a company (corporate market)

• Contract “signed”

A contract newly created on Worldline Card Issuing gets this status. In this contract, terms and conditions between the issuer and cardholder(s) are reflected such as :

• Transaction and mark up fees,
• Card event related fees (i.e. replacement, PIN selection etc.),
• Velocity (i.e. maximum amount per transaction, maximum spending amount etc.),
• Wallet “ready” option: capability to onboard the card in wallets (i.e. Apple/Google/Samsung Pay etc.)
• 3D Secure / ACS option: decide if the card can perform 3D secure check
• Instant Issuing option: decide if the card credentials have to be immediately available (PAN, expiry date, CVx2, cardholder name) without waiting for a physical plastic card.

Note that in this state, updates are always possible (i.e. change of fees, velocity on a card product included in the contract, addition of a new card product). Some updates will only be applicable for next card(s) issued in this contract such as card design, or embossing name for instance.

• Contract “suspended”

A contract can be suspended at any time. This will directly impact all the card(s) belonging to this contract by “blocking” them temporarily. The removal of a suspension can be done either on demand or automatically at the end of a period that was set when you’ve suspended the contract.

• Contract “closed”

Contracts can be ended at any time and for any reasons (i.e. cardholder leaves the bank) either on demand or automatically based on the “standard” rules below:

• All cards belonging to a contract have reached their expiry date with no automatic renewals,
• The end of a contract was scheduled.

Each card issued through Worldline Card Issuing follows the general card lifecycle highlighted :

• Card Created

Cards will start their lives on Worldline Card Issuing on Issuers’ demands either by calling our APIs or sharing with us a provisioning file. Each card will be created using:

• The card account information (IBAN) précised by the Issuer,
• Limits and fees settings defined by the Issuer when he has created the card product on Worldline Card Issuing,
• The BIN ranges selected by the Issuer[1]

Based on these data, Worldline Card Issuing:

• Generates cards’ numbers/PAN, cards’ PINs and will calculate expiry dates (card variable data),
• Generates and send a cardholder file (for physical crd) to the Embosser selected by the Issuer.

• Card Active

Cards can be automatically activated or not, depending on the choice of the Issuer when defining its card product on Worldline Card Issuing. For cards not immediately active, 3 options are available to make them active:

• On demand through an API call,
• On demand through our WL Card Issuing Portal.
• Automatically at the 1^st PIN based approved authorization

• Card Blocking

Worldline Card Issuing supports both “temporary” and “permanent” blocking. Unlike “temporary” blocking which is reversible, “permanent” blocking is definitive and will be mainly used in case of fraud, lost or stolen. When a “permanent” blocking will be requested on a card, Worldline Card Issuing will:

• Decline authorizations coming from this card,
• Notify the scheme associated to this card,
• Stop the renewal of the card

• Card Deactivated

Card deactivation is also not reversible and can be done on WL Card Issuing through 5 ways:

• On demand,
• Automatically on expiry date,
• At the contract termination,
• X days after a replacement,
• After the 1^st use of the new card following a renewal.

• Card Cancellation

A card will be in this state on WL Card Issuing if any issue occurs during the card production (i.e. errors
when generating card data or errors on the embosser side).

[1] BIN can be owned by the Issuer itself or, as an option covered by Worldline through its sponsorship license.

The data preparation feature aims at collecting, generating and preparing all the data needed by the embosser to produce the card and personalize the chip card applications.

Worldline Card Issuing supports in “standard” the production of Card Order Files using XML format and based on EMV Card Personalization Specification (CSP). In terms of security, AES encryption mechanism is used to cypher sensitive data. Once produced, these files are compressed (ZIP format), encrypted using RSA standard and sent to the embosser.

As a return from the embosser, Worldline Card Issuing expects to receive from the embosser a file containing the personalization status.

A similar approach is used to generate and send files related to PIN distribution.

PIN creation

Regarding PIN creation, two strategies are available for an Issuer on Worldline Card Issuing:

• Either creating cards with an initial PIN randomly generated by our solution,
• Or creating cards with PIN selected by cardholders.

When a card is about to expire, this latter is usually renewed to offer to the cardholder a continuity in his card payment experience. Worldline Card Issuing offers 2 renewal mode automatic or “on-demand”.

Automatic renewal

In this mode, the production of new cards will be launched automatically X days before reaching the expiry date of cards in circulation. This delay can be set by the issuer on the platform.

Note that on top of checking dates, additional verifications are done by Worldline Card Issuing on:

• The card status: when a card is “blocked”, this latter cannot be renewed,
• The age of the cardholder: for instance prepaid card for kids,
• The existence of any programmed card deactivation or contract closing rules for which a renewal doesn’t make sense

On-demand renewal

In this mode, the issuer will control the renewal of each card of his portfolio manually.

Whatever the mode selected, cards will be renewed using the same PAN and the same PIN. Worldline Card Issuing also supports renewal with new PAN and/or PIN.

Several scenario may lead to the replacement of the card such as: card defect (PIN non compromised), embossing name change, lost or stolen card.

For card defect or embossing name change cases, Worldline Card Issuing will order a new card reusing the same PAN/PIN/Expiry date whereas these data will be generated again for lost/stolen cases.

Note that before ordering a replacement, Worldline Card Issuing will perform verifications on:

• The card and contract status: preventing from replacing a card which is blocked or for which the related contract is suspended,
• The expiry date of current card: to avoid launching a replacement for cards having a renewal date coming soon,
• The existence of any programmed card deactivation or contract closing rules for which a replacement doesn’t make sense.