ob-data-ais-s1

Redirect flow with Date filter only

Account holder's (PSU) consent is needed to access their bank accounts details. In the Redirect Authorisation approach, the browser session of the account holder is redirected from your software / Worldline Bank Selection Interface to mock bank. In that case the mock bank provides all the pages required for authentication (usually username, password). After that the account holder is redirected to Worldline Open Banking Service and from there back to your software.

Take the following steps to complete this scenario.

Step - 1 : Get the list of connected banks

  • Call Reach API (GET /aspsp) to obtain a list of supported banks. 
  • Check API response of a record with ASPSP ID = "20101" and Name = "Account Information redirect + Transaction Date filter".
  • Details and Options section provide a list of API endpoints  and mandatory fields that need to be used for successful account data request towards the mock bank using redirect mode of authorisation .
  • Remark: Details of reach information provided in the sandbox environment are limited and for informational purpose to give you an idea about how reach information looks like. 

Step - 2 : Initiate consent

  • Call the POST /consents API to obtain account holder's consent. 
  • In response of POST /consents, you will receive consent ID, a redirect link to authorise the consent and a link to call GET /consent/status API to get the status of the consent.
  • You will can choose various combination of permissions to access account data:      
    • "Accounts" - Only list of accounts can be retrieved. Balances and transaction details cannot be requested.
    • "Accounts", "Balances" - You can only request accounts and balances details for requested accounts.
    • "Accounts", "Transactions" - You can request list of accounts and transaction details for requested accounts.
    • "Accounts", "Balances", "Transactions" -You can request list of accounts, balances and transaction details for requested accounts. 
    • If there's no permissions provided in request, by default "Accounts", "Balances", "Transactions" permission will be used.
  • If "OwnerName" indicator set to "true" in consents request, you can receive actual owner name (if supported and provided by the mock bank) in the response of GET /accounts API.
  • "TransactionFromDateTime" and "TransactionToDateTime" can be provided in POST /consents request, so that you could access a list of transactions within a specific time period only.
  • Currently below fields are being ignored in POST /consents request in the sandbox environment but supported in live environment:
    • ValidUntilDate,
    • FrequencyPerDay,
    • RecurringIndicatior,
    • CombinedServiceIndicator,
    • PreferredScaMethod
  • If GET /consents/status endpoint has been called before user provides their approval, you will receive consent status = "Open" from the mock bank in response.

Step - 3 : Authorise or reject the consent

  • With the redirect link received in response of POST /consents, the account holder is redirected to the login page of mock bank. 
  • On this login page, the account holder can provide dummy (any) credential details as the log in page is for example purpose only.
  • Once the account holder provides their dummy credentials, they are redirected to a page with "Approve" & "Deny" buttons to authorise or reject the data access.
  • Once the account holder clicks on Approve or Deny button, the consent is created with an appropriate status and the account holder is redirected back to your software.
  • Remark : Mock bank pages were created for the testing purpose only. The actual implementation depends on bank's PSD2 implementation.

Step - 4 : Get consent status

  • Call the GET /consents/status API to get the latest consent status from the mock bank.
  • If consent is authorised by the account holder, you will receive consent status = "Authorised".
  • If consent is denied by the account holder, you will receive consent status = "Rejected" as a final consent status.

Step - 5 : Get list of accounts

  • Once the consent is authorised by the customer (PSU), call the GET /accounts API to obtain list of accounts.

Step - 6 : Get balances details

  • Once you obtain a list of accounts, call GET /balances API to get the balance details of respective account.

Step - 7 : Get transaction details

  • Call the GET /transactions API to retrieve transactions details of respective account. 
  • In sandbox environment you can try out the below functionalities of GET /transactions API:
    • Get transaction data for specific date range using "dateFrom" & "dateTo" query parameters. Transaction data is returned based on date without time as this might also happen in the live environment. 
  • If the mock bank responds with large number of transactions, you may receive a paginated transactions response.
  • In case of paginated response, you can retrieve appropriate transaction page using "first", "next", "previous", "last", "self" links provided in the response.

Sequence Diagram

AIS with Redirect Authorisation
Enable "on this page" menu on doc section
On

ob-data-ais-sand

List of Account Information Service Scenarios

Below you'll find a list of account data testing scenarios. Each scenario has a separate page including a step by step description of the steps to complete the scenario. You can choose a scenario by providing the corresponding ASPSP ID in the request, which initiates the consent.

To simplify the interaction, these scenario's work with a static token which doesn't expire. This sandbox token is supplied in the API reference.

You can use the sandbox:

  • either on the API reference page (only for registered users, look for the 'try' button) or
  • with a tool like Postman
Sr. No.Scenario NameASPSP IDScenario Guideline
01.Redirect Flow With Date Filter Only (accounts, balances and transactions are retrieved)  20101Read more
02.Redirect Flow With DateTime Filter (accounts, balances and transactions are retrieved)  20116Read more
03.Download Transactions 20102Read more
04.Delete Consents 20101Read more

 

Enable "on this page" menu on doc section
On

ob-data-ais-api

Consent Initiation

API Reference

Consent scope

Account data is only provided with the consent of the account holder.  Consent can be given according to three permission groups where a combination of the 3 groups is possible:

  • Accounts
  • Balances
  • Transactions 

The consent can be granted to all accounts or to specific accounts depending whether account holder's bank supports the detailed consent.

POST Consents

Endpoint: POST /psus/{psuId}/consents

Base URL: /xs2a/routingservice/services/ob/ais/v3

This endpoint is used to set up a consent for an account holder for a specific bank. Depending on the bank's API the possible combinations of permissions and account references differ.  Use Permissions body parameter to specify what information you wish to obtain (accounts and / or balances and / or transactions). In case it was not provided, the default (access to all) is used.

In case recurring consent is needed, you should use the body parameter ‘RecurringIndicator’ = True. The default behavior is to request a recurring consent valid for 180 days unless the ValidUntilDate is provided.

Supported consent flows will be determined by the Links section of the response.

 

Data model

Request (click to enlarge)Response (click to enlarge)
Post consent requestPost consent response

Multi-level SCA

We support the Multi-Level SCA. In this case consent has to be authorized by multiple account holders. There are no specific endpoints defined for this. The single authorizations have to be started explicitly by the POST Authorization endpoint for each single account holder.

Enable "on this page" menu on doc section
On

ob-data-ais-reach

Reach Directory API

API Reference

The Reach Directory API allows to retrieve a list of all connected banks and their details such as bank's name and bank's id. It is sufficient to refresh the list of banks once a day. For each bank we provide additional information on their PSD2 implementation, which you need to take into account while implementing consent management and data retrieval. The additional information is split into 2 parts - 'Details' and 'Options'.

Once you retrieve the list of supported banks, you will present it to the user either through the screens you have built or through Worldline Bank Selection interface. Once user bank is selected, you will need to check in Reach API response whether the selected bank requires pre-authentication or you can initiate the consent straight away.

GET ASPSPs

Endpoint: GET /aspsps

The base URL for the Reach Directory is: /xs2a/routingservice/services/directory/v3 

This endpoint is used to retrieve the reach directory.

Data model

RequestResponse (click to enlarge)
Get reach requestGet reach response

Example

Request

curl -X GET "https://xs2a.awltest.de/xs2a/routingservice/services/directory/v3/aspsps?allDetails=true&allOptions=true&allAspspSpecificFields=true" 
-H "accept: application/json" 
-H "X-Request-ID: abcdef2e-3000-4000-88cc-ae40e3b113d7" 
-H "MessageCreateDateTime: 2023-09-25T08:15:00.856Z" 
-H "Service: AIS" 
-H "Authorization: Bearer dc9833a74c712d8c7a50476e71768a1f"

Response body

{
  "Service": "AIS",
  "Groups": [],
  "ASPSP": [
    {
      "AspspId": "20101",
      "Name": [
        {
          "Label": "Account information redirect + Transaction date filter",
          "Language": "en"
        }
      ],
      "Country": "XX",
      "CategoryLabel": [
        "Retail"
      ],
      "Details": [
        {
          "Api": "POST /psus/{psuId}/aspsps/{aspspId}/consents/{consentId}/identification",
          "Fieldname": "preferredScaMethod",
          "Type": "SUPPORTED",
          "Value": "REDIRECT",
          "ProtocolVersion": "BG_V_1_3_6"
        }
      ],
      "Options": [],
      "BIC": "XXAIS001"
    },
    {
      "AspspId": "20116",
      "Name": [
        {
          "Label": "Account information redirect + Transaction datetime filter",
          "Language": "en"
        }
      ],
      "Country": "XX",
      "CategoryLabel": [],
      "Details": [
        {
          "Api": "POST /psus/{psuId}/aspsps/{aspspId}/consents/{consentId}/identification",
          "Fieldname": "preferredScaMethod",
          "Type": "SUPPORTED",
          "Value": "REDIRECT",
          "ProtocolVersion": "STET_V_1_4_2_1_7"
        }
      ],
      "Options": [],
      "BIC": "XXAIS001"
    },
    {
      "AspspId": "20102",
      "Name": [
        {
          "Label": "Account information redirect + Download transactions",
          "Language": "en"
        }
      ],
      "Country": "FR",
      "CategoryLabel": [
        "Retail"
      ],
      "Details": [
        {
          "Api": "POST /psus/{psuId}/aspsps/{aspspId}/consents/{consentId}/identification",
          "Fieldname": "preferredScaMethod",
          "Type": "SUPPORTED",
          "Value": "REDIRECT",
          "ProtocolVersion": "BG_V_1_3_6"
        }
      ],
      "Options": [],
      "BIC": "XXAIS001"
    }
  ]
}

Response - Details section

The Details section in the reach directory response consists of the following fields:

  • Api - information on specific endpoints supported or not supported by the bank.
  • FieldName - name of a header or a body field.
  • Type - restriction of the API endpoint or API field.
  • Value - list of supported field values separated by ‘|’.
  • ProtocolVersion -  API version used by the bank. Can be ignored.

If there is no FieldName, the Type describes whether this endpoint is available (SUPPORTED) or not (UNSUPPORTED):

TypeAPI endpoint support
UNSUPPORTEDThe mentioned Api is not supported by account holder's bank, you will receive an error if it’s used.
SUPPORTED

The mentioned Api is supported by account holder's bank. 

If POST is supported, the corresponding API methods (GET, PUT, DELETE) are also supported, if defined in the swagger.

If the FieldName is given, the Type is describing whether the field is UNSUPPORTED, SUPPORTED, MANDATORY or FORBIDDEN. The table below specifies the rules for the Type-FieldName combination:

Type FieldName restrictions
UNSUPPORTEDThe FieldName  is not supported. If mentioned FieldName is provided in request,  you will receive an error.
SUPPORTEDThe field mentioned in FieldName is supported and you need to use one of the values provided in the Value field. If you won't provide a specific value in the request, a default value will be used. If an unsupported value is used, you will receive an error.
MANDATORYThe mentioned FieldName is mandatory and has to be filled with one of the values in the Value field. In case Value field does not contain specific value, you can use any value. If you won't provide a specific value in the request or use an unsupported value, you will receive an error.
FORBIDDENThe mentioned FieldName is forbidden. If used, you will receive an error.

Example 1 - Api without FieldName 

An example for API endpoint without the FieldName is the pre-authentication API. For most banks, a pre-authentication is not supported. For those banks where a pre-authentication is possible there is a record in the Details section:

"Api": "POST /psus/{psuId}/Aspsps/{aspspId}/pre-authentication",
"Type": "SUPPORTED",
"ProtocolVersion": "BG_V_1_3_0"

Example 2 - Api combined with FieldName

The example below indicates that from the 'preferredScaMethod' enumeration only the value 'REDIRECT' can be used.


"Api": "POST /psus/{psuId}/aspsps/{aspspId}/consents",
"Fieldname": "preferredScaMethod",
"Type": "SUPPORTED",
"Value": "REDIRECT",
"ProtocolVersion": "STET_V_1_4_2_1_7"

Response - Options section

The Options section provides information regarding the way of using API endpoints for specific bank similar to the Details section. But the information given here is not that specifically related a single API endpoint. It is more to be seen as a parameter for the bank.

Since the Options are not defined for a single endpoint there is no Api attribute given for the single options. Instead they have two keys (Key1 and Key2) identifying the use of the single Option. An example:

"Key1": "PREAUTH_MANDATORY",
"Value": "1",
"Level": "INFORMATIONAL"

In this case for the given bank pre-authentication is mandatory because the value is set to 1. The setting of 1 is reflecting that the option is set. A list of possible option keys is given below. The Key2 is currently not used. It is foreseen to allow definition of grouped options having the same main key Key1 and a different sub-key key2. An example for options provided in the Reach API is shown below:

Key1Key2ValueLevelDescription
PREAUTH_MANDATORY 1, 0INFORMATIONAL

The pre-authentication (regardless whether being done implicitly or explicitly) is mandatory.

Default 0

PREAUTH_EXPLICIT_REQUIRED 1, 0CRITICALPre-authentication has to be done explicitly by the POST pre-authentication endpoint.

 

Enable "on this page" menu on doc section
On

ob-data-ais

Account Data

As account holder needs to grant access to their data, the process of retrieving account data consists of several main steps, also visible in the diagram below:

  1. Consent preparation
  2. Consent initiation
  3. Consent authorisation
  4. Data retrieval

We prepared a set of functions supporting these steps (the white boxes in the diagram). Each of those functions have a page with more explanation. You can choose how to integrate:

  • Using Worldline Open Banking functions directly. This allows you to control the user experience, but will require more integration effort due to various combinations of authorisation flows.
  • Using ready-to-go components (Bank Selection Interface and Push Notification). This will provide you with a streamlined integration due to a set of white labeled screens which support bank selection and guide users through the consent steps while handling the complexity of consent authorisation flows. Additionally, you can choose to receive push notifications during the initiation and authorisation phase of the consent whenever the consent status changes.

Data retrieval is done with API's during the validity time of the consent (up to 6 months). You can consult consent's validity by using dedicated get consent status endpoint.

Account Data Overview
Enable "on this page" menu on doc section
On

ob-data-initservice

Bank Selection Interface

for Data

API Reference

 

Typical Steps

The Bank Selection Interface provides a set of white labeled screens which support account holder's bank selection and capturing of additional information required for certain authorisation flows. The Bank Selection Interface will simplify the integration effort for the Initiating Party by handling the pre-authentication and consent initiation flows. It can be used by setting the field UseAuthorisationLandingPages= true in the Consent request.

A few screenshots below show how the screens look on a mobile device with the Worldline branding. The majority of the elements can be customised to support your branding. 

 

Step 1: Bank Selection

Step 2: Authorize access

Step 3: Account Selection

Step 4: You can now retrieve the data

Users quickly find their bank: 

 

We highlight popular ones and provide a blazing-fast search experience. 

After the user validates their identity through the bank’s online banking or mobile app (redirect or decoupled flow). The screenshot below shows a possible embedded flow, where Bank Selection Interface collects user credentials prior to sending them to the bank.

User selects one or more bank accounts for which the data access will be granted.

The user allowed their bank to share the data, so now you can retrieve the account details.

Bank Selection Interface Data step 1Bank Selection Interface Data Step 2Bank Selection Interface Data step 3

 

Bank Selection Interface Data step 4

 

 

Enable "on this page" menu on doc section
On

Cards: General Features

General Features

Remind current PIN of the card

     API Reference

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.

Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once. The response will be retrieved directly from our system.

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, the related accounts and the selected models linked to the card contract.

API links

POST /api/v2/issuers/{issuerId}/cards/search

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

GET /api/v2/issuers/{issuerId}/cards/{cardReference}/blocking-information

GET /api/v2/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/blocking-information

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 can be used but it will no longer evolve. It is recommended to use the Block card API.

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

PATCH /api/v2/issuers/{issuerId}/cards/{cardReference}/blocking-information

PATCH /api/v2/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/blocking-information

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 can be used but it will no longer evolve. It is recommended to use the Block all cards API.

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

POST /api/v2/issuers/{issuerId}/cards/update-all-blocking-information

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.

Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once. The response will be retrieved directly from our system.

API links

POST /api/v2/issuers/{issuerId}/cards/{cardReference}/create-emergency-card

POST /api/v2/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/create-emergency-card

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.

Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once. The response will be retrieved directly from our system.

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

POST /api/v2/issuers/{issuerId}/cards/{cardReference}/display-cvv

POST /api/v2/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/display-cvv

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

POST /api/v2/issuers/{issuerId}/cards/{cardReference}/display-pin

POST /api/v2/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/display-pin

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

POST /api/v2/issuers/{issuerId}/cards/{cardReference}/pin

POST /api/v2/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/pin

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.

Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once. The response will be retrieved directly from our system.

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

POST /api/v2/issuers/{issuerId}/cards/{cardReference}/reset-pin-try-counter

POST /api/v2/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/reset-pin-try-counter

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

POST /api/v2/issuers/{issuerId}/cards/{cardReference}/advise-product-extension

POST /api/v2/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/advise-product-extension

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

GET/api/v2/issuers/{issuerId}/cards/{cardReference}/prefilled-letter-templates/{letterTemplateReference}

GET/api/v2/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/prefilled-letter-templates/{letterTemplateReference}

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

GET/api/v2/issuers/{issuerId}/cards/letter-templates

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

GET/api/v2/issuers/{issuerId}/cards/letter-templates/{letterTemplateReference}

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

GET/api/v2/issuers/{issuerId}/cards/{cardReference}/letters/{letterId}

GET/api/v2/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/letters/{letterId}

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.

Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once. The response will be retrieved directly from our system.

API links

POST/api/v2/issuers/{issuerId}/cards/{cardReference}/generate-letter

POST/api/v2/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/generate-letter

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

POST/api/v2/issuers/{issuerId}/cards/{cardReference}/letters/{letterId}/validate

POST/api/v2/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/letters/{letterId}/validate

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

DELETE/api/v2/issuers/{issuerId}/cards/{cardReference}/letters/{letterId}

DELETE/api/v2/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/letters/{letterId}

Release orders for a card

The API allows orders (card order, PIN mailer order, TAN mailer order) related to a card to be released in case a bank validation is required (before starting the embossing process).

The bank validation must be configured in the card creation model corresponding to the order reason (in renewal model for renewal treatment…).

The main input fields requested by the API are:

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

As a result, the orders related to the requested card are orderable.

API links

POST/api/v2/issuers/{issuerId}/cards/{cardReference}/release-orders

POST/api/v2/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/release-orders

Display PIN for a card by PAN + PSN and/or expiry date

API links

POST/api/v2/issuers/{issuerId}/cards/display-pin

Set PIN for a card by PAN + PSN and/or expiry date

API links

POST/api/v2/issuers/{issuerId}/cards/pin

Declare a counterfeit card

The API allows a counterfeit card to be declared.

The PAN of the counterfeit card must be provided.

The expiry date and/or the psn can be provided.

It is possible to indicate if the card has been compromised in Common Point of Purchase (card is in CPP list).

Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once. The response will be retrieved directly from our system.

API links

POST/api/v2/issuers/{issuerId}/cards/declare-counterfeit-card

Enable "on this page" menu on doc section
On

Merchant payments

API reference Transactions doc

Merchant payments

 

This API enables you to retrieve comprehensive payment data using specific criteria and periods of time.

  • Show payments data in your application of preference
  • The merchant payments are matched with PAID status transactions in the Transactions API for reconciliation purposes
  • Acquirers can allow third parties access to retrieve own merchant payments data

 

GET Merchant payments calls

Request parameters in bold on the Merchant payments API reference page are mandatory to complete a call.

To ensure best search call response time please use as many parameters as available.

There are two types of GET METHOD calls:

  • GET call to Search using one or more query parameters (e.g. paymentReference, merchantHierarchyId, merchantId, contractId and iban). Valid calls return a list of payment results
  • GET calls to retrieve a Specific entity (e.g. paymentId) – returns a particular payment result

 

Enable "on this page" menu on doc section
On
Subscribe to