A card is a payment mean that enables a customer to access funds or make purchases against a line of credit.

In our solution each Card is identified by a unique cardReference and optionally by a unique issuerCardExternalReference per Issuer.

The first Card of a Card Contract is created at the same time than the Card Contract.

Card information can be retrieved using the two following endpoints : 

• Retrieve the card information : GET /issuers/{issuerId}/cards/{cardReference}
• Search cards by pan and panSequenceNumber and/or expiryDate : POST /issuers/{issuerId}/cards/{cardReference}/search

Card Lifecycle

The following picture illustrates the card lifecycle and possible card status transition.

The following APIs could be used to manage card lifecycle : 

• Activate a card : POST /issuers/{issuerId}/cards/{cardReference}/activate
• Deactivate a card : POST /issuers/{issuerId}/cards/{cardReference}/deactivate
• Block a card : POST /issuers/{issuerId}/cards/{cardReference}/block
• Unblock a card : POST /issuers/{issuerId}/cards/{cardReference}/unblock

Card Replacement and Renewal

The user can use the API to replace an existing card and create a new one. As input the replacement reason (e.g. old card was lost, stolen, is defective, name change) need to be provided. Both PAN and expiry date of the new card are calculated following the rules defined in the Product configuration for the provided replacement reason.

POST /issuers/{issuerId}/cards/{cardReference}/replace

The renewal of the card can be managed automatically in our solution, an automatic process is triggered when card is close to expire and a new card is created replacing the existing card.

A Card Contract represents a single card owner by a cardholder and is linked to a card profile which defines all allowed business rules (e.g. replacement, renewal) and card properties (e.g. chip data) required to create a card. Under a card contract the first card is created and all next cards in case of automatic renewals, card replacements.

Each Card Contract is identified by a unique cardContractReference and optionally by a unique issuerCardContractExternalReference per Issuer.

The Card Contract information can be managed with the following endpoints:

• Retrieve Card Contract: GET /issuers/{issuerId}/card-contracts/{cardContractReference}
• Retrieve cardholder for a  Card Contract: GET /issuers/{issuerId}/card-contracts/{cardContractReference}/cardholder
• Retrieve contract for a given Card Contract: GET /issuers/{issuerId}/card-contracts/{cardContractReference}/contract
• List cards for a given Card Contract: GET /issuers/{issuerId}/card-contracts/{cardContractReference}/cards

Contract refers to the Customer contracts created in our solution. The contract inherits default value from Product with the possibility to override  some specific parameters, such as fees, terms and conditions, credit limit, card layout reference.

Each Contract is identified by a unique contractReference and optionally by a unique issuerContractExternalReference per Issuer.

 

Contract Creation

In order to create a contract for a customer, the API Create consumer contract is used : POST /issuers/{issuerId}/contracts/create-consumer-contract

As a prerequisite to create a contract and its related Cards and Accounts, the Issuer and Product should be configured and their references known by the Issuer. Cards and Accounts are created according to the product configuration

The request is composed of two parts

• an optional list of customers to be created and that could be used as contractOwner, cardHolder, or accountOwner. By default the contractOwner is the cardHolder and the accountOwner.
• the contract structure referring to the Product via the issuerProductExternalReference and the different Card (cardTemplateReference) and Account (accountTemplateReference) Templates defined for this Product. The attributes of the request could be used to override some of the default behaviors defined at Product level

{
   "customers":[
      {
         "requestCorrelationId":"1",
         "courtesyTitle":"Mrs",
         "lastName":"Lena",
         "firstName":"Broderick",
         "addresses":[
            {
               "addressLabel":"MAIN_POSTAL_ADDRESS",
               "addressType":"POSTAL_MAIL",
               "postalAddress":{
                  "line1":"address_line1_string_1",
                  "country":"country_string_1"
               }
            }
         ]
      }
   ],
   "contract":{
      "issuerProductExternalReference":"issuerProductExternalReference",
      "contractOwnerRequestCorrelationId":"1",
      "accountHierarchy":{
         "accounts":[
            {
               "accountTemplateReference":"RootAccountTemplateReference"
            },
            {
               "accountTemplateReference":"ChildAccountTemplateReference"
            }
         ]
      },
      "cardContracts":[
         {
            "cardTemplateReference":"cardTemplateReference"
         }
      ]
   }
}

As a result the Contract is created for the customer with its Card Contracts and Accounts. 

Adding additional cards and accounts

To add cards and related accounts to an existing contract use the following endpoint  : POST /issuers/{issuerId}/contracts/{contractReference}/add-cards-accounts by providing the issuerId of the Issuer and contractReference identifying the Contract.

Contract Closure

Contracts can be closed either immediately or scheduled using the endpoint POST /issuers/{issuerId}/contracts/{contractReference}/close

 

Other Contract APIs

Furthermore the contracts can be managed through the following endpoints:

• Retrieve contract data : GET /issuers/{issuerId}/contracts/{contractReference}
• Retrieve contract owner : GET /issuers/{issuerId}/contracts/{contractReference}/contract-owner
• List accounts for a given contract : GET /issuers/{issuerId}/contracts/{contractReference}/accounts
• List card contracts for a given contract : GET /issuers/{issuerId}/contracts/{contractReference}/card-contracts

 

A Customer address can be of different types as postal address, email address or phone number.

The appropriate address type will be selected depending on the business usage, as example for statement sending or card delivery. 

The customer addresses could be created during the creation of the Contract or when additional Cards and Accounts are created.

A customer should at least have one main address (addressLabel: MAIN_POSTAL_ADDRESS)

 

Each Address is identified by a unique addressReference and optionally by a unique issuerAddressExternalReference per Issuer.

 

An Issuer can create additional addresses for a customer using the API Create address for a customer : POST /issuers/{issuerId}/customers/{customerReference}/addresses by providing the issuerId of the Issuer and customerReference identifying the Customer.

 

Furthermore the addresses could me managed and updated through the following endpoints:

• Retrieve customer address : GET /issuers/{issuerId}/customers/{customerReference}/addresses/{addressReference}
• Update address :  PUT /issuers/{issuerId}/customers/{customerReference}/addresses/{addressReference}
• Deactivate address : POST /issuers/{issuerId}/customers/{customerReference}/addresses/{addressReference}/deactivate
• Activate address :  POST /issuers/{issuerId}/customers/{customerReference}/addresses/{addressReference}/activate

 

A customer is a person or a company who has subscribed to services offered by the Issuer.

A customer can have multiple roles and can be the owner of the Contract, the Cardholder, the owner of the Account

 

Each Customer is identified by a unique customerReference and optionally by a unique issuerCustomerExternalReference per Issuer.

 

The customer is created during the creation of the Contract or when additional Cards and Accounts are provided.

POST /issuers/{issuerId}/contracts/create-consumer-contract (by providing customers information)

POST /issuers/{issuerId}/contracts/{contractReference}/add-cards-accounts (by providing customers information)

 

In order to retrieve customer information, the API GET /issuers/{issuerId}/customers/{customerReference} should be used by providing the issuerId of the Issuer and customerReference identifying the Customer.

Customer data could be updated using  the API PUT /issuers/{issuerId}/customers/{customerReference} 

 

Each customer can have :

• one or many contracts that can be retrieved using the API GET /issuers/{issuerId}/customers/{customerReference}/contracts
• one or many accounts  that can be retrieved using the API GET /issuers/{issuerId}/customers/{customerReference}/accounts
• one or multiple cards that can be retrieved using the API GET /issuers/{issuerId}/customers/{customerReference}/card-contracts

The Product represents what is sold to a Customer.

Products are organized in product catalogue, that is a specific set of products for an issuer.

A product is a set of parameters and features that defines the behavior and functionalities of a set of Cards and Accounts.

 

The configuration of the product is performed by Worldline based on Issuer requirements through the definition of templates linked to the product

These templates are used in the APIs in order to facilitate the creation of the Contract and its associated Cards and Accounts

POST /issuers/{issuerId}/contracts/create-consumer-contract (by providing issuerProductExternalReference, cardTemplateReference and accountTemplateReference)

POST /issuers/{issuerId}/contracts/{contractReference}/add-cards-accounts (by providing issuerProductExtensionExternalReference)

 

An Issuer is a bank or financial organization that makes debit, credit, and/or prepaid cards available to consumers on behalf of payment card schemes.

Our solution support issuers hierarchy as presented in the picture, so that the product catalogue could be shared across the bank group and its subsidiaries while leaving the possibility for subsidiaries to define their own products and functionalities at their level

Each Issuer (or sub-issuers) is identified by a unique issuerId which is to be used in all the business APIs endpoints.

The list of issuers that are authorized for a given client can be retrieved using the following API: GET /issuers/

 

Introduction

WL 1-Click Card Issuing Processing provides end-to-end and real time processing by managing debit, credit and prepaid cards. The core services allow you to launch your card product quickly and easily.

The WL 1-Click Card Issuing Processing API has been designed as a REST API.

Each resource is accessible under a clearly named URL and the HTTP response codes are used to relay status. HTTP Verbs like GET and POST are used to interact with the resources. To ease the integration with clients, main resources are identified either using issuer references either internal references generated on WL systems.

JSON is used for all payloads, including metadata information.

Authentication

WL 1-Click 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 access_token by calling our Oauth2 Authentication server and then try out the APIs via the developer portal or your app.

Request:
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'

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

Response codes

WL 1-Click Card Issuing Processing 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

Metadata

WL 1-Click 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)

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

Request correlation identifier

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 WL system as an UUID.

Pagination

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}}

Request with default offset:
{{baseUrl}}/issuers/{{issuerId}}/accounts/{{accountReference}}/operations?page=5

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

Field expansion

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

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

Field filtering

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 (,)

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

Versionning

The major versions of the WL 1-Click 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.

 

 

 

Issuer

An issuer is a financial organization that makes debit, credit, and/or prepaid cards available to consumers on behalf of payment card schemes. It could be a bank or another supervised financial institution.

 

Product

The product represents what is sold to a customer. A product is a set of parameters and features that defines the behavior and functionalities of a set of cards and accounts. For example, card product parameters determine the renewal rules, the card account working mode, if there are specific transaction fees and/or membership fee. Further card product parameters define limits and velocity controls to restrict where and how associated cards are used. 

 

Customer

A customer is a person or a company who has subscribed to services offered by the issuer.

 

Address

A customer address is the generic term for postal address, email address or phone number. Addresses can be of two types, personal address or company address, and could be used in several ways according to the purpose for which the address is used, as example for statement sending or card delivery. 

 

Contract

Contract refers to the Customer contracts created in our solution. The contract is the link between cards, accounts and customer data. The contract inherits default value from Product with the possibility to override  some specific parameters, such as fees, terms and conditions, credit limit, card layout reference.

 

Card Contract

A Card Contract represents a single card owner by a cardholder and is linked to a card profile which defines all allowed business rules (e.g. replacement, renewal) and card properties (e.g. chip data) required to create a card. Under a card contract the first card is created and all next cards in case of automatic renewals, card replacements.

 

Card

A card is a payment mean that enables a customer to access funds or make purchases against a line of credit. Cards can have different technologies (EMV, Magnetic Stripe, Contactless), could be physical or virtual.

 

Order

An order refers to card order and PIN mailer data extractions that are sent to card producer and PIN mailer editors respectively.

 

Account

Accounts manage monetary operations, balances and restrictions, and are typically assigned to account owners. An account owner is typically an individual, or a legal entity, who has signed a contract with an issuing institution, so a customer.

Accounts are used to process operations, manage a balance in a dedicated currency,  control the credit risk, perform transaction charging, calculate interests (credit or debit), generate an invoice (statement), process payments.

 

Operation

Operations can be transactions received from clearing or internal generated operations ( e.g. fees, refund, chargeback...)  that are posted on accounts.

 

Authorization

Authorizations are request message from a connected scheme which are processed by our authorization server. Based on several business rules (e.g. card status, velocity limits check ...) the authorizations could either be accepted or declined.

 

Authorization Business Case

An authorization business case can refer to one or several consecutive Authorizations (for example, a reservation in a hotel with a subsequent confirmation or a purchase with a subsequent cancellation).

 

Temporary Credit Limit

A temporary credit limit, that extends or reduces the account credit limit could be defined at account level. In this case, the value of the temporary limit override the content of the normal credit limit

 

Authorization Restriction

The card usage can be restricted using multiple criteria, such as transaction type (ecom, ATM), acceptance domain (allowed regions), active start and end date. 

 

Authorization Restriction Override

Restrictions are either enabled or disabled by default and can be overridden.

 

Velocity Limit

The velocity limit is a restriction based on usage frequency and the total amount on the card account. The purpose of a velocity limit is to limit a transaction in terms of amount and frequency, e.g. it might be allowed to withdraw 500€ per day on POS terminals in Europe.

 

Velocity Limit Override

On account level the defaults can be overridden. Overriding can be timely restricted by providing an activation period.