ob-data-ais-sand

Read more about 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 Name	ASPSP ID	Scenario Guideline
01.	Redirect Flow With Date Filter Only (accounts, balances and transactions are retrieved)	20101	Read more
02.	Redirect Flow With DateTime Filter (accounts, balances and transactions are retrieved)	20116	Read more
03.	Download Transactions	20102	Read more
04.	Delete Consents	20101	Read more

ob-data-ais-api

Read more about 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)

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.

ob-data-ais-reach

Read more about 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

Request	Response (click to enlarge)

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):

Type	API endpoint support
UNSUPPORTED	The 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.

Type

API endpoint support

UNSUPPORTED

The 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
UNSUPPORTED	The FieldName is not supported. If mentioned FieldName is provided in request, you will receive an error.
SUPPORTED	The 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.
MANDATORY	The 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.
FORBIDDEN	The 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:

Key1	Key2	Value	Level	Description
PREAUTH_MANDATORY		1, 0	INFORMATIONAL	The pre-authentication (regardless whether being done implicitly or explicitly) is mandatory. Default 0
PREAUTH_EXPLICIT_REQUIRED		1, 0	CRITICAL	Pre-authentication has to be done explicitly by the POST pre-authentication endpoint.

Key1

Key2

Value

Level

Description

PREAUTH_MANDATORY

1, 0

INFORMATIONAL

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

Default 0

PREAUTH_EXPLICIT_REQUIRED

1, 0

CRITICAL

Pre-authentication has to be done explicitly by the POST pre-authentication endpoint.

ob-data-ais-transactionflow

Read more about ob-data-ais-transactionflow

ais transaction flow

ob-data-ais

Read more about 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:

Consent preparation
Consent initiation
Consent authorisation
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.

ob-data-initservice

Read more about ob-data-initservice

Bank Selection Interface

for Data

API Reference

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

Cards: General Features

Read more about Cards: General Features

General Features

Remind current PIN of the card

The API allows a PIN reminder to be requested for a card, identified by the Issuer Card External Reference or the Card Reference when a cardholder forgot its PIN.

The card must be in “ACTIVE” status.

As a result, a PIN mailer order is generated.

API links

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

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

Request data:

{
           "sendingMode":"Normal",
           "deliveryType":"CUSTOMER"
        }

Response data:

{
           "responseMetadata":{
              "correlationId":"2b54aa5c-aaf7-4b93-b6b2-5e12b92fa16b",
              "statusMessage":"Executed successfully",
              "statusCode":200,
              "responseDateTime":"2023-01-03T15:14:13.531+0100",
              "timeTakenMs":206
           },
           "data":{
              "orderIdentifier":{
                 "orderReference":"202301032000000000389047"
              },
              "currentInternalStatus":"ORDERABLE",
              "orderType":"PinMailerOrder"
           }
        }

Retrieve Card

This API enables card information for a given card identifier to be retrieved.

The response can also be enriched (if specified as embedded fields in input) with additional data such as the status history of the card, the card Contract information, the card order identifiers linked to the card.

API links

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

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

Below an example of request for

The issuer: 1234
Card reference: 2000000000386135

POST /api/v2/issuers/1234/cards/2000000000386135

Response data:

{
   "data":{
      "issuerId":"1234",
      "cardIdentifier":{
         "cardReference":"2000000000386135",
         "issuerCardExternalReference":"EXTREF_CARD_REF_MCI_ABC_CNT_235644290"
      },
      "pan":"5212137209162844",
      "maskedPan":"521213******2844",
      "expiryDate":"1227",
      "panSequenceNumber":"1",
      "status":"ACTIVE",
      "statusDate":"2022-12-22T11:18:11.973+00:00",
      "embossingName":"REMY NAME",
      "artwork":"12340001",
      "permanentlyBlocked":false,
      "emergencyCard":false,
      "emergencyCashAdvance":false,
      "renewed":false,
      "replaced":false,
      "cardContractIdentifier":{
         "cardContractReference":"12342000000000386134",
         "issuerCardContractExternalReference":"EXTREF_CARD_CRT_REF_MCI_ABC_CNT_235644290"
      },
      "isCardDigitalizationAllowed":false,
      "panReference":"2011231c953ee52147efb5a43d532c8fa43f",
      "cardScheme":"MASTERCARD",
      "virtual":false,
      "techAndAppModelName":"M_1234_APPTEC_MCI",
      "contractType":"CONSUMER"
   }
}

Search card with PAN, PAN sequence number and expiry date

This API enables card information to be retrieved based on PAN or PAN reference, and optionally on PAN sequence number and/or expiry date information as search criteria.

The response can be enriched (if specified as embedded fields in input) with additional data such as the status history of the card, the card Contract information, the card order identifiers linked to the card, card identifiers of the new card in case of replacement or renewal.

API links

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 is no more maintained. The block card API must be used instead.

The API enables blocking information related to a given card to be updated such as:

Blocking reason among those available for the issuer
Blocking detail
Lost and stolen date if the blocking reason is LOST or STOLEN
The fraud process
The flag indicating whether the card is in a CPP list
The flag indicating whether the PIN is compromised
Scheduled blocking information : delay or blocking reason if the delay is not yet reached

API links

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 is no more maintained. The block all cards API must be used instead.

The API is similar to “Update blocking information for a card” API but is applied to all cards having the same PAN or same PAN reference.

Blocking information can be updated such as:
Blocking reason among those available for the issuer
Blocking detail
Lost and stolen date if the blocking reason is LOST or STOLEN
The fraud process
The flag indicating whether the card is in a CPP list
The flag indicating whether the PIN is compromised
Scheduled blocking information : delay or blocking reason if the delay is not yet reached

In response, card information for each matched card is provided.

API links

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.

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.

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.

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.

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}

SMD API

Technical Description

Stock Market Data service provides a lot of APIs like :

If you want to test APIs, please contact us to get an authentication token

View Documentation

Read more about SMD API

Merchant payments

Read more about 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

Card lifecycle management

Read more about Card lifecycle management

Card Lifecycle Management

Worldline supports the whole card lifecycle.

Please find below an illustration of the possible transitions from one status to another

Activate a card

An issuer can activate a card on demand from Issuer Card External Reference or Card Reference only if the card is in CREATED status.

The issuer chooses the activation reason from the customised reasons previously configured.

As a result, the card is active in our system.

Note : The issuer can alternatively use one of the options offered by WL system to activate a card such as:

Directly when the card is created
or at first PIN based approved authorization

API links

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

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

Block a card

The API allows to block a card permanently (immediately or in the future) or to block a card temporarily depending on the configured blocking reason by using the Issuer Card External Reference or the Card Reference.

The card is in “CREATED” or “ACTIVE” status.

The blocking reason is chosen among the reasons configured beforehand for the issuer.

Example of use cases :

Use case 1: The card is blocked permanently, in case of lost, stolen, not delivered, fraudulent activity, for example.

The issuer can provide:

Transfer Effective Date – estimated date when the card was lost or stolen
If the PIN is compromised
If the card is lost or stolen:
- Lost Stolen Date
If the card is lost:
- Loss Circumstances

As a result, the card is definitively blocked in our system (final status).

Next online authorizations are declined for the card.

If the card is permanently blocked, it can be notified to the scheme (card exceptions file sent to Stoplist network).

Use case 2: The card has been compromised in Common Point of Purchase (CPP) : a permanent card blocking is scheduled for the card and the cardholder is still allowed to use its card for PIN based transactions by the issuer.

The issuer indicates that the card has been compromised in a Common Point of Purchase (cppFlag) and provides the delay to block the card in the future (scheduledCardBlockingDelay)

As a result, the card is still active in our system and a permanent card blocking is scheduled for the card.

Authorizations are still accepted for the card.

The card is effectively blocked via batch process once the scheduled permanent card blocking date is reached.

Use case 3: The card is blocked temporarily in case of fraud suspicion by e.g. Issuer or Fraud system.

Fraud information as free text (fraud code) can be provided and can be used later (e.g. in dispute management in case there is a fraud declared on this card)

As a result, the card is temporarily blocked in our system and can be unblocked later.

Next online authorizations are declined for the card.

It is also possible to update the following blocking information by this API :

When the card is already blocked:
- Blocking reason among those available for the issuer
- Blocking detail
- Lost and stolen date if the blocking reason is LOST or STOLEN
- Fraud process
- The flag indicating whether the PIN is compromised
- Scheduled blocking information : delay or blocking reason if the delay is not yet reached
When the card is active :
- Scheduled blocking information : delay or blocking reason if the delay is not yet reached

API links

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

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

Example : Request for permanent blocking reason

Issuer: 1234
CardReference: 2000000000374460
Blocking reason: LOST

POST /api/v2/issuers/1234/cards/2000000000374460/block

Request data

{
                   "blockingReason":"LOST",
                   "blockingReasonDetail":"LOST",
                   "comment":"comment",
                   "contactData":"contactData",
                   "customerRequestingBlockDate":"2022-10-14T08:14:08.493Z",
                   "fraudCode":"01",
                   "lastUsageDate":"2022-10-11T11:14:08.493Z",
                   "lastUsagePlace":"lastUsage",
                   "lossCircumstances":"lossCircumstances",
                   "lossCountry":"lossCountry",
                   "lossPlace":"lossPlace",
                   "lossReportedBy":"lossReportedBy",
                   "lossReportedVia":"lossReportedVia",
                   "lostStolenDate":"2022-10-11T11:14:08.493Z",
                   "noReplacementReason":"tempAddr",
                   "pinCompromised":true,
                   "transferEffectiveDate":"2022-10-14T08:14:08.493Z"
                }

Response data

"data":{
                   "cardIdentifier":{
                      "cardReference":"2000000000374460"
                   },
                   "status":"BLOCKED",
                   "blockingReason":"LOST",
                   "blockingReasonDetail":"LOST",
                   "cardBlockingDateTime":"2022-12-05T16:16:19.514+00:00"
                }

Unblock a card

An issuer can reactivate a temporarily blocked card.

The card is in temporary “Blocked” status.

The issuer identifies the card with their own reference (Issuer Card External Reference) or with the reference generated by WL (Card Reference).

The issuer chooses the unblocking reason from the reasons configured beforehand for him.

As a result, the card is active again in our system.

An issuer cannot request the unblocking of a permanently blocked card.

API links

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

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

Block all cards with same PAN or same PAN reference

The API is similar to Block a card API but is applied to all cards having the same PAN or same PAN reference.

The API allows the permanent blocking (immediately or in the future), or temporary blocking, depending on the configured blocking reason, of all cards having the same PAN or same PAN reference.

Cards must be in “CREATED” or “ACTIVE” status.

The blocking reason is chosen from the reasons configured beforehand for the issuer

It is also possible to update the following blocking information by this API :

When the card is already blocked:
- Blocking reason among those available for the issuer
- Blocking detail
- Lost and stolen date if the blocking reason is LOST or STOLEN
- Fraud process
- The flag indicating whether the PIN is compromised
- Scheduled blocking information : delay or blocking reason if the delay is not yet reached
When the card is active :
- Scheduled blocking information : delay or blocking reason if the delay is not yet reached

API links

POST /api/v2/issuers/{issuerId}/cards/block-all

Unblock all cards with same PAN or same PAN reference

The API is similar to Unblock a card API but is applied to all cards having the same PAN or same PAN reference.

The API allows the unblocking of all cards having the same PAN or same PAN reference.

Cards must be in temporary “Blocked” status.

The unblocking reason is chosen from the reasons configured beforehand for the issuer.

The Issuer cannot request this API for permanently blocked cards.

As a result, cards having the same PAN or same PAN reference are active again in our system.

API links

POST /api/v2/issuers/{issuerId}/cards/unblock-all

Deactivate a card

The API allows an active card, or a temporary blocked card, to be deactivated on demand, by using the Issuer Card External Reference or the Card Reference.

The deactivation reason is chosen from the reasons configured beforehand for the issuer.

As a result, the card is deactivated in our system.

This process is not reversible. New card authorizations are declined. If necessary, a request for a card replacement may be made by the issuer.

This API allows also to cancel a card in “Created” status, e.g., when the card production has failed.

API links

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

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

Replace a card

The API allows a card, that has not yet been replaced or renewed, to be replaced when the card is lost/stolen or damaged, or when the customer’s information has changed, by using the Issuer Card External Reference or the Card Reference.

The card contract must be ACTIVE with no replacement blocking and the card must not be in CREATED status.

The replacement reason is chosen from the reasons configured beforehand for the issuer.

Data that may need to be changed during replacement can be provided, such as: card data (e.g., embossing name), order data (e.g., card producer if several are allowed), customer data (e.g., name), PIN.

As a result, the new card is created, a card order and a PIN mailer order are created when applicable (physical card requested).

In case a product change on renewal is planned on the contract of the card to be replaced, the card will not be replaced but the product change will be forced instead. From the request, only blocking reason and embossingName/embossingName2ndLine will be considered :

If blocking reason is provided (for temporary blocking only), the new card of the new contract is blocked with this reason
If embossingName and/or embossingName2ndLine are provided, they will be appplied to the old card and will be transferred to the new card of the new contract.

In the request response, information related to the new contract and the product change will be returned.

API links

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

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

Example Replacement Request for LOST_STOLEN replacement reason

Issuer: 1234
CardReference: 2000000000374460
replacement reason: LOST_STOLEN

POST /api/v2/issuers/1234/cards/2000000000374460/replace

Request data:

{
           "waiveFee":false,
           "replacementReason":"LOST_STOLEN",
           "cardContract":{
              "specificFields":{
                 "additionalProp1":"string",
                 "additionalProp2":"string",
                 "additionalProp3":"string"
              },
              "card":{
                 "issuerCardExternalReference":"CARD-20221119",
                 "cardOrder":{
                    "specificFields":{
                       "additionalProp1":"string",
                       "additionalProp2":"string",
                       "additionalProp3":"string"
                    },
                    "sendingMode":"Normal"
                 }
              }
           },
           "overrideDistributionRules":false
        }

Response data:

"data":{
           "card":{
              "cardIdentifier":{
                 "cardReference":"2000000000374491",
                 "issuerCardExternalReference":"CARD-20221119"
              },
              "pan":"4546174672045636",
              "maskedPan":"454617******2386",
              "expiryDate":"1227",
              "panSequenceNumber":"1",
              "status":"ACTIVE",
              "replacementFor":{
                 "cardReference":"2000000000374460"
              },
              "orders":[
                 {
                    "orderIdentifier":{
                       "orderReference":"202212052000000000374492"
                    },
                    "orderType":"CardOrder",
                    "currentInternalStatus":"ORDERABLE"
                 }
              ],
              "panReference":"1500d015027a202e47b39d56e25aab9fcc1d"
           },
           "replacementForCardStatus":"BLOCKED",
           "replacementReason":"LOST_STOLEN",
           "cardReplacementDateTime":"2022-12-05T16:27:57.340+00:00"
        }

Block and replace a card

The API allows a card identified by the Issuer Card External Reference or the Card Reference to be blocked and replaced.

This API regroups Block a card (for card blocking or blocking information update) and Replace a card APIs in a single request.

As result, the card is blocked and the new card is created.

If any error occurs while card blocking or card replacing, the card is neither blocked nor replaced.

With this API, it is also possible to block all cards having the same PAN than the card referenced by Issuer Card External Reference or the Card Reference. In this case Block all cards API is called instead Block a card API.

In case a product change on renewal is planned on the contract of the card to be replaced, the card will not be replaced but the product change will be forced instead. From the replace card request, only blocking reason and embossingName/embossingName2ndLine will be considered :

If blocking reason is provided (for temporary blocking only), the new card of the new contract is blocked with this reason
If embossingName and/or embossingName2ndLine are provided, they will be applied to the old card and will be transferred to the new card of the new contract.

In the request response, information related to the new contract and the product change will be returned.

API links

POST /api/v2/issuers/{issuerId}/cards/{cardReference}/block-and-replace

POST /api/v2/issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/block-and-replace

Subscribe to