ob-data-initservice

Read more about ob-data-initservice

Bank Selection Interface

for Data

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}

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

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

Payment Account to Account

View Documentation

Read more about Payment Account to Account

General Contract Management

Read more about General Contract Management

General Contract Management

Create A Consumer Contract

The Create Consumer Contract API allows the creation of a new consumer contract already signed by the customer or not, and its first card(s), either with physical support (plastic) or not (virtual card).

Pre-conditions:

The correlation ID, if provided by the issuer, must be unique. In case of re-use of a correlation ID from an existing contract, the system will return the data from the existing contract (e.g., if the API call returns a "time-out“ response, the same correlation ID can be provided to retrieve contract data from WL system for further checks).
An active consumer product exists with a physical or pure virtual card.

The issuer can request the creation of a new consumer contract from the provided active consumer product with additional information such as

the contract is already signed (status as "SIGNED") by the customer or not (status as "AWAITING_SIGNATURE")
The issuer can provide a list of new customers or the references to existing customers in Worldline system

As a result, the contract is created:

with the provided status by the issuer: either the contract is already signed (its account hierarchy is immediately in "ACTIVE" status) or not (its account hierarchy is in "AWAITING_SIGNATURE" status)
with each card and its status set to created or active, depending on the card product configuration
with related card order to produce the physical card, if plastic required and the pin mailer order if required.

The API response returns newly created contract information such as

the new contract itself
the different identifiers such as the contract reference, contract owner, account owner, add-on, card contract, card and cardholder. Each identifier is composed of the Worldline internal reference and the external reference (is not present if not provided by the issuer and not generated by any algorithm)

The references are used to: retrieve/update/close contracts, list accounts for a contract, retrieve the contract owner for a contract, retrieve/update legitimacy documents, etc..

Additional information for credit card when creating the contract

it is possible to provide a customized credit limit amount value (e.g. after credit scoring)
it is possible to provide SEPA mandate data to send a direct debit note to the debtor’s bank to repay the cyclic due amount
it is possible to provide an insurance package (in order to calculate insurance fees) and to activate it (insuranceEventCode)

Additional information for prepaid card when creating the contract

the credit limit amount is equal to 0 and cannot be changed during contract lifetime
it is possible to provide SEPA mandate data to send a direct debit note to the debtor’s bank in case offline transactions have to be repaid (note that our system can put on hold such offline transactions that lead the prepaid account to a debit position, waiting for payment by the customer)

API links

POST /api/v2/issuers/{issuerId}/contracts/create-consumer-contract

Below is an example where the data for customer creation is provided in the request:

POST /api/v2/issuers/1234/contracts/create-consumer-contract

Request data

"data":{
   " ""customers":" "[
      "        "{
         "/* Comment":"here is provided the customer required to create this contract. This customer is the contract owner (see above contractOwnerRequestCorrelationId"": "92"). Then it is also the account owner of the account “issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212050001""and also the cardholder of the card by automatic inheritance. */ 

            ""addresses":" "[
            "                "{
               "addressLabel":" ""MAIN_POSTAL_ADDRESS",
               "                    ""addressType":" ""POSTAL_MAIL",
               "                    ""issuerAddressExternalReference":" ""ADDRESS-202212050001",
               "                    ""postalAddress":" "{
                  "                        ""line1":" ""Belziger 70",
                  "                        ""line2":" ""Test line2",
                  "                        ""townName":" ""BERLIN",
                  "                        ""country":" ""DE""                    "
               }"                "
            }"            "
         ],
         "            ""birthDate":" ""1970-10-22T00:00Z",
         "            ""birthPlace":" ""London",
         "            ""courtesyTitle":" ""Mr",
         "            ""firstName":" ""John",
         "            ""issuerCustomerExternalReference":" ""PERSON-202212050001",
         "            ""lastName":" ""SMITH",
         "            ""commercialStatus":" ""Normal",
         "            ""onlineRiskCategory":" ""Standard",
         "            ""offlineRiskCategory":" ""Standard",
         "            ""requestCorrelationId":" ""92",
         "/* is used in the rest of the message to assign this new customer as e.g. contract owner",
         "account owner",
         "cardholder) */ 

            ""sex":" ""M",
         "            ""nationality":" ""DE""        "
      }"/* Another new customer can be provided if contract owner and account owner or cardholder are not the same */ 
    "
   ]"    ""contract":" "{
      "        ""accountHierarchy":" "{
         "            ""accounts":" "[
            "                "{
               "                    ""accountTemplateReference":" ""T_1234_ACC_ROOT_VISA_DEBIT_CLASSIC",
               "                    ""bic":" ""XXXDEBB",
               "                    ""iban":" ""DE02500105174128973163",
               "                    ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212050001""                "
            },
            "                "{
               "                    ""accountTemplateReference":" ""T_1234_ACC_CHILD_VISA_DEBIT_CLASSIC",
               "                    ""bic":" ""XXXDEBB",
               "                    ""iban":" ""DE02500105174128973163",
               "                    ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212050001""                "
            }"            "
         ]"        "
      },
      "        ""cardContracts":" "[
         "            "{
            "      ""card":" "{
               "                    ""cardOrder":" "{
                  "                        ""sendingMode":" ""Normal""                    "
               },
               "                    ""issuerCardExternalReference":" ""CARD-202212050001""                "
            },
            "                ""cardTemplateReference":" ""T_1234_CARD_VISA_DEBIT_CLASSIC",
            "                ""forcedEmbossingName":" ""SMITH JOHN",
            "                ""forcedEmbossingName2ndLine":" ""STEVEN",
            "                ""issuerCardContractExternalReference":" ""CARD_CONTRACT-202212050001""            "
         }"        "
      ],
      "        ""cardReleaseOrder":" ""AUTOMATIC",
      "        ""contractOwnerRequestCorrelationId":" ""92",
      /* the new customer provided in the list of customers above and identiied by correlationId as “92” is assigned to contract owner role */ 

        "issuerContractExternalReference":" ""CONTRACT-202212050001",
      "        ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
      "        ""issuerBranchCode":" ""NO_BRANCH""    "
   }
}

Response data

"data":{
   " ""contract":" "{
      "            ""contractIdentifier":" "{
         "                ""contractReference":" ""4459f986-5242-4202-9ed5-f652573e9f63",
         "                ""issuerContractExternalReference":" ""CONTRACT-202212050001""            "
      },
      "            ""status":" ""SIGNED",
      "            ""creationDate":" ""2022-12-05T12:34:43.770+00:00",
      "            ""signatureDate":" ""2022-12-05T12:34:43.758+00:00",
      "            ""issuerBranchCode":" ""NO_BRANCH",
      "            ""cardReleaseOrder":" ""AUTOMATIC",
      "            ""productIdentifier":" "{
         "                ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
         "                ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC""            "
      },
      "            ""contractOwnerIdentifier":" "{
         "            ""customerReference":" ""CUS10000346472",
         "            ""issuerCustomerExternalReference":" ""PERSON-202212050001""            "
      },
      "            ""accounts":" "[
         "                "{
            "accountIdentifier":" "{
               "                 ""accountReference":" ""12348505533653587133",
               "                 ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212050001""                    "
            },
            "                    ""root":" false",
            "                    ""status":" ""ACTIVE",
            "                    ""accountOwnerIdentifier":" "{
               "                    ""customerReference":" ""CUS10000346472",
               "                    ""issuerCustomerExternalReference":" ""PERSON-202212050001""                    "
            },
            "                    ""accountGuarantorIdentifier":" "{
               "                    ""customerReference":" ""CUS10000346472",
               "                   ""issuerCustomerExternalReference":" ""PERSON-202212050001""                    "
            }"                "
         },
         "                "{
            "accountIdentifier":" "{
               "                  ""accountReference":" ""12346621070985963583",
               "                ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212050001""                    "
            },
            "                    ""root":" true",
            "                    ""status":" ""ACTIVE",
            "                    ""accountOwnerIdentifier":" "{
               "                    ""customerReference":" ""CUS10000346472",
               "                    ""issuerCustomerExternalReference":" ""PERSON-202212050001""                    "
            },
            "                   ""accountGuarantorIdentifier":" "{
               "                        ""customerReference":" ""CUS10000346472",
               "                        ""issuerCustomerExternalReference":" ""PERSON-202212050001""                    "
            }"                "
         }"            "
      ],
      "            ""cardContracts":" "[
         "                "{
            "  ""cardContractIdentifier":" "{
               "                    ""cardContractReference":" ""12342000000000374437",
               "                    ""issuerCardContractExternalReference":" ""CARD_CONTRACT-202212050001""                    "
            },
            "                    ""cardHolderIdentifier":" "{
               "                       ""customerReference":" ""CUS10000346472",
               "                        ""issuerCustomerExternalReference":" ""PERSON-202212050001""                    "
            },
            "                    ""status":" ""ACTIVE",
            "                    ""principalSupplementaryCardIndicator":" ""PRINCIPAL",
            "                    ""card":" "{
               "                        ""cardIdentifier":" "{
                  "                           ""cardReference":" ""2000000000374438",
                  "                            ""issuerCardExternalReference":" ""CARD-202212050001""                        "
               },
               "                        ""pan":" ""4546177060616413",
               "                        ""maskedPan":" ""454617******6413",
               "                        ""expiryDate":" ""1227",
               "                        ""panSequenceNumber":" ""1",
               "                        ""status":" ""ACTIVE",
               "                        ""orders":" "[
                  "                            "{
                     "                                ""orderIdentifier":" "{
                        "                                    ""orderReference":" ""202212052000000000374439""                                "
                     },
                     "                                ""orderType":" ""CardOrder",
                     "                                ""currentInternalStatus":" ""ORDERABLE""                            "
                  }"                        "
               ],
               "                        ""panReference":" ""1500fc52cb34fa714bf3bd94c9421d38c79c""                    "
            },
            "                    ""relatedAccounts":" "[
               "                       "{
                  "                            ""relation":" ""DEFAULT",
                  "                            ""accountIdentifier":" "{
                     "                                ""accountReference":" ""12348505533653587133",
                     "                               ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212050001""                            "
                  }"                        "
               }"                    "
            ]"                "
         }"            "
      ]"        "
   },
   "        ""customers":" "[
      "            "{
         "                ""customerIdentifier":" "{
            "                    ""customerReference":" ""CUS10000346472",
            "                    ""issuerCustomerExternalReference":" ""PERSON-202212050001""                "
         },
         "                ""courtesyTitle":" ""Mr",
         "                ""lastName":" ""SMITH",
         "                ""firstName":" ""John",
         "                ""addresses":" "[
            "                    "{
               "                        ""addressIdentifier":" "{
                  "                            ""addressReference":" ""ADDREF_MAIN_POSTAL_ADDRESS_1000000000385897",
                  "                            ""issuerAddressExternalReference":" ""ADDRESS-202212050001""                        "
               },
               "                        ""addressLabel":" ""MAIN_POSTAL_ADDRESS",
               "                        ""addressType":" ""POSTAL_MAIL""                    "
            }"                "
         ]"            "
      }"        "
   ]"    "
}
}
}

Search Contracts By criteria

This API is no more maintained. The Global search for contracts API must be used instead to retrieve consumer contracts by criteria (multi issuers).

The API provides possibility to retrieve a list of consumer contracts for an issuer, based on certain criteria.

One of the following criteria for searching must be provided:

either account's criteria
or customer's criteria
or card's criteria

For searching with account's criteria, only one of the following data must be provided :

IBAN
or account identifier : either account reference or issuer account external reference
or account membership number 1
or account membership number 2

For searching with customer's criteria, only one of the following data must be provided :

Customer Attributes with last name and first name (and optionally with birth date, postal address : postal code, street name and/or building number, phonetic criteria : phonetic search and/or phonetic algorithm)
or customer identifier : either customer reference or issuer customer external reference
or partner external reference

For searching with card's criteria, only one of the following data must be provided :

PAN
or card contract identifier : either card contract reference or issuer card contract external reference
or card identifier : either card reference or issuer card external reference

If requested, the API input parameters allows also to:

limit the list of returned cards per card contract to either the latest card only or all previous cards
return the direct parent account in the hierarchy of the account and/or the list of child accounts of the account matching the criteria if the research is based on account's criteria
request to enrich the response with additional data relative to the accounts, the card contracts, the cards and the customers by using embedded fields

The API response contains all matched contracts and for each returned contract some information is provided such as :

contract identifier with the contract reference, the issuer external contract reference if originally provided
product change information if any, such as its current status, new product, new contract if it exists
embedded fields if requested such as list of all customers or identifiers linked to this contract (e.g. contract owner, root account owner, cardholder(s)), accounts and account identifiers, card contracts, cards

API links

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

Retrieve Contract

This API allows the retrieval of a particular contract from its reference or its issuer external reference.

The API response contains contract information, such as:

contract identifier with the contract reference and the issuer external contract reference if previously provided
product change information, such as its current status (scheduled, done, cancelled), new product, new contract - if it exists
embedded fields, if requested, such as the list of all customers or identifiers linked to this contract (e.g., contract owner, root account owner, cardholder(s)), card contracts

API links

GET /api/v2/issuers/{issuerId}/contracts/{contractReference}

GET /api/v2/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}

Below an example of a request for:

The contract: 4459f986-5242-4202-9ed5-f652573e9f63
The issuer: 1234

GET /api/v2/issuers/1234/contracts/4459f986-5242-4202-9ed5-f652573e9f63

Response data

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

Below a second example of a request for:

The contract: 1e9802ae-68db-467b-8610-ae59f0d37291
The issuer: 1234

With requested embedded field: cardContracts

In the response, the 3 card contracts are provided.

GET /api/v2/issuers/1234/contracts/1e9802ae-68db-467b-8610-ae59f0d37291?embed=cardContracts

Response data

"data":{
           "        ""issuerId":" ""1234",
           "        ""contractIdentifier":" "{
              "            ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
              "            ""issuerContractExternalReference":" ""CONTRACT-202212130001""        "
           },
           "        ""issuerBranchCode":" ""NO_BRANCH",
           "        ""cardReleaseOrder":" ""AUTOMATIC",
           "        ""numberOfFreeCardsPrimaryCardImpacted":" false",
           "        ""signatureDate":" ""2022-12-13T14:40:21.000+00:00",
           "        ""status":" ""SIGNED",
           "        ""statusDate":" ""2022-12-13T14:40:21.000+00:00",
           "        ""cardContracts":" "[
              "            "{
                 "                ""issuerId":" ""1234",
                 "                ""cardContractIdentifier":" "{
                    "                    ""cardContractReference":" ""12342000000000380697""                "
                 },
                 "                ""cardTemplateReference":" ""T_1234_CARD_VISA_DEBIT_CLASSIC",
                 "                ""cardTypeCode":" ""F",
                 "                ""status":" ""ACTIVE",
                 "                ""openingDate":" ""2022-12-13T15:25:57.710+00:00",
                 "                ""activationDate":" ""2022-12-13T15:25:57.730+00:00",
                 "                ""trustedAuthenticationReference":" ""123420221213162557294",
                 "                ""newCardRenewalAllowed":" true",
                 "                ""issuerBranchCode":" ""NO_BRANCH",
                 "                ""artwork":" ""DebitClassic",
                 "                ""forcedEmbossingName":" ""BOUBOU",
                 "                ""schemeDeclarationOptOut":" false",
                 "                ""principalSupplementaryCardIndicator":" ""SUPPLEMENTARY",
                 "                ""productCategory":" ""DEBIT",
                 "                ""productCategoryLabel":" ""IMMEDIATE_DEBIT_DEBIT",
                 "                ""productIdentifier":" "{
                    "                    ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
                    "                    ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC""                "
                 },
                 "                ""cardHolderIdentifier":" "{
                    "                    ""customerReference":" ""CUS10000351532",
                    "                    ""issuerCustomerExternalReference":" "" PERSON-202212130001B""                "
                 },
                 "                ""vipFlag":" false",
                 "                ""contractIdentifier":" "{
                    "                    ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
                    "                    ""issuerContractExternalReference":" ""CONTRACT-202212130001""                "
                 },
                 "                ""cardProfileDescription":" ""P_1234_CARD_VISA_DEBIT_CLASSIC",
                 "                ""cardProfileReference":" ""P_1234_CARD_VISA_DEBIT_CLASSIC""            "
              },
              "            "{
                 "                ""issuerId":" ""1234",
                 "                ""cardContractIdentifier":" "{
                    "                    ""cardContractReference":" ""12342000000000380694",
                    "                    ""issuerCardContractExternalReference":" ""CARD_CONTRACT-202212130001""                "
                 },
                 "                ""cardTemplateReference":" ""T_1234_CARD_VISA_DEBIT_CLASSIC",
                 "                ""cardTypeCode":" ""F",
                 "                ""status":" ""ACTIVE",
                 "                ""openingDate":" ""2022-12-13T14:40:21.527+00:00",
                 "                ""activationDate":" ""2022-12-13T14:40:21.527+00:00",
                 "                ""trustedAuthenticationReference":" ""123420221213154021607",
                 "                ""newCardRenewalAllowed":" true",
                 "                ""issuerBranchCode":" ""NO_BRANCH",
                 "                ""artwork":" ""DebitClassic",
                 "                ""forcedEmbossingName":" ""BOUBOU*TEST BOUBOU EMBOSS2",
                 "                ""schemeDeclarationOptOut":" false",
                 "                ""principalSupplementaryCardIndicator":" ""PRINCIPAL",
                 "                ""productCategory":" ""DEBIT",
                 "                ""productCategoryLabel":" ""IMMEDIATE_DEBIT_DEBIT",
                 "                ""productIdentifier":" "{
                    "                    ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
                    "                    ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC""                "
                 },
                 "                ""cardHolderIdentifier":" "{
                    "                    ""customerReference":" ""CUS10000351531",
                    "                    ""issuerCustomerExternalReference":" ""PERSON-202212130001""                "
                 },
                 "                ""vipFlag":" false",
                 "                ""contractIdentifier":" "{
                    "                    ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
                    "                    ""issuerContractExternalReference":" ""CONTRACT-202212130001""                "
                 },
                 "                ""cardProfileDescription":" ""P_1234_CARD_VISA_DEBIT_CLASSIC",
                 "                ""cardProfileReference":" ""P_1234_CARD_VISA_DEBIT_CLASSIC""            "
              },
              "            "{
                 "                ""issuerId":" ""1234",
                 "                ""cardContractIdentifier":" "{
                    "                    ""cardContractReference":" ""12342000000000380700""                "
                 },
                 "                ""cardTemplateReference":" ""T_1234_CARD_VISA_DEBIT_CLASSIC",
                 "                ""cardTypeCode":" ""F",
                 "                ""status":" ""ACTIVE",
                 "                ""openingDate":" ""2022-12-13T16:54:15.002+00:00",
                 "                ""activationDate":" ""2022-12-13T16:54:15.112+00:00",
                 "                ""trustedAuthenticationReference":" ""123420221213175415246",
                 "                ""newCardRenewalAllowed":" true",
                 "                ""issuerBranchCode":" ""NO_BRANCH",
                 "                ""artwork":" ""DebitClassic",
                 "                ""forcedEmbossingName":" ""BOUBOU",
                 "                ""schemeDeclarationOptOut":" false",
                 "                ""principalSupplementaryCardIndicator":" ""SUPPLEMENTARY",
                 "                ""productCategory":" ""DEBIT",
                 "                ""productCategoryLabel":" ""IMMEDIATE_DEBIT_DEBIT",
                 "                ""productIdentifier":" "{
                    "                    ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
                    "                    ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC""                "
                 },
                 "                ""cardHolderIdentifier":" "{
                    "                    ""customerReference":" ""CUS10000351533",
                    "                    ""issuerCustomerExternalReference":" ""PERSON-202212130001C""                "
                 },
                 "                ""vipFlag":" false",
                 "                ""contractIdentifier":" "{
                    "                    ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
                    "                    ""issuerContractExternalReference":" ""CONTRACT-202212130001""                "
                 },
                 "                ""cardProfileDescription":" ""P_1234_CARD_VISA_DEBIT_CLASSIC",
                 "                ""cardProfileReference":" ""P_1234_CARD_VISA_DEBIT_CLASSIC""            "
              }"        "
           ],
           "        ""contractOwnerIdentifier":" "{
              "            ""customerReference":" ""CUS10000351531",
              "            ""issuerCustomerExternalReference":" ""PERSON-202212130001""        "
           },
           "        ""productIdentifier":" "{
              "            ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
              "            ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC""        "
           },
           "        ""rootAccountIdentifier":" "{
              "            ""accountReference":" ""12343652199237560111",
              "            ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212130001""        "
           }"    "
        }
        }

Update Addresses Of All Contract Members

This API is used to update all members of a given contract with same provided address (including address usages).

E.g., for Contract A, contract owner, cardholders 1 and 2 are updated simultaneously with the same Main postal address data.

This API is used also:

to invalidate a particular address of all members of a contract by setting the flag "invalid" to True and providing only the address label and the address type (limited to address type as postalAddress). All the other data are ignored.
or to provide a valid address for all contract members by setting the flag "invalid" to False (default value) and providing the address label, the address type and the valid address (limited to address type as postalAddress)’

Each provided address must have

an addressLabel among the ones configured such as MAIN_POSTAL_ADDRESS
an address type to indicate whether it a postal, an e-mail or a phone number
the address itself depending on its type: MailAddress, EmailAddress or PhoneNumber

Each provided address can have

none, 1,... N address usages. Such address usages can be used to retrieve the address related to a business process (e.g. CARD_DELIVERY used to identify the address to be used to send the card to the cardholder).
startDate: this is the date when the provided address becomes valid. If not provided this is by default the current date.

API links

POST /api/v2/issuers/{issuerId}/contracts/{contractReference}/update-all-customers-addresses

POST /api/v2/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/update-all-customers-addresses

POST /api/v2/issuers/1234/contracts/1e9802ae-68db-467b-8610-ae59f0d37291/update-all-customers-addresses

Request data

{
           "  ""addresses":" "[
              "    "{
                 "      ""addressLabel":" ""MAIN_POSTAL_ADDRESS",
                 "      ""addressType":" ""POSTAL_MAIL",
                 "      ""postalAddress":" "{
                    "        ""line1":" ""50 AVENUE LAMARTINE",
                    "        ""line3":" ""string",
                    "        ""line4":" ""string",
                    "        ""line5":" ""string",
                    "        ""buildingNumber":" ""50",
                    "        ""streetName":" ""AVENUE LAMARTINE",
                    "        ""postCode":" ""75010",
                    "        ""townName":" ""PARIS",
                    "        ""country":" ""FR""      "
                 },
                 "      ""startDate":" ""2022-12-13T16:37:26.625Z""    "
              }"  "
           ]
        }

Response data

"data":" "{
           {
              "        ""contractIdentifier":" "{
                 "            ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
                 "            ""issuerContractExternalReference":" ""CONTRACT-202212130001""        "
              },
              "        ""customers":" "[
                 "            "{
                    "                ""customerIdentifier":" "{
                       "                    ""customerReference":" ""CUS10000351531",
                       "                    ""issuerCustomerExternalReference":" ""PERSON-202212130001""                "
                    },
                    "                ""addresses":" "[
                       "                    "{
                          "                        ""addressIdentifier":" "{
                             "                            ""addressReference":" ""ADDREF_MAIN_POSTAL_ADDRESS_1000000000392073""                        "
                          },
                          "                        ""addressLabel":" ""MAIN_POSTAL_ADDRESS",
                          "                        ""addressType":" ""POSTAL_MAIL""                    "
                       }"                "
                    ]"            "
                 },
                 "            "{
                    "                ""customerIdentifier":" "{
                       "                    ""customerReference":" ""CUS10000351532",
                       "                    ""issuerCustomerExternalReference":" ""HOME_ADDR_REF_PERSON-202212130001B""                "
                    },
                    "                ""addresses":" "[
                       "                    "{
                          "                        ""addressIdentifier":" "{
                             "                            ""addressReference":" ""ADDREF_MAIN_POSTAL_ADDRESS_1000000000392074""                        "
                          },
                          "                        ""addressLabel":" ""MAIN_POSTAL_ADDRESS",
                          "                        ""addressType":" ""POSTAL_MAIL""                    "
                       }"                "
                    ]"            "
                 }"        "
              ]"    "
           }
        }

Add Card To An Existing Contract

This API allows an issuer to add a new card (debit, credit, prepaid, either physical or virtual), a new account to an existing contract, together or independently, from a product extension among those allowed by the product used to instantiate the contract.

This product extension is usually composed of both card and account products, but can be composed of a card or several cards only, or of one or several accounts only or combination of both cards and accounts. It leads to create a new card and a new card account within the contract (multiple contents of product extensions can be configured depending on issuer's needs).

The new card account is in most of the cases attached to the root account of the hierarchy (default behaviour) but the issuer can provide its parent account if it is not the root (complex account hierarchy with more than 2 account levels).

The issuer shall provide required data for each account and card contract/card if required (depends on product extension configuration).

The issuer can provide:

a list of new customers or the references to existing customers in Worldline system
the legitimacy document(s) per customer
different membership fee and account setup fee (contract fees) if needed per account

The issuer can choose to receive in response for the extended/updated contract new resources created only or all resources (e.g. already existing accounts, card contracts, cards).

In case it is configured that adding additional card and account should trigger a product change, and there is an already scheduled product change, then the product change will be initiated and the new card and account will be created in the new contract.

The API response returns the extended contract with information related to account(s), card contract(s) and card(s) (limited to newly created account(s) and card contract(s)/card(s) if requested).

Add Cards and Accounts Request

API links

POST /api/v2/issuers/{issuerId}/contracts/{contractReference}/add-cards-accounts

POST /api/v2/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/add-cards-accounts

Below, an example of a request to add a card to:

The existing contract: 1e9802ae-68db-467b-8610-ae59f0d37291
Issuer: 1234
for a new customer (Helen BOUBOU)

With the parameter “newResourcesOnly” set to true, only the created card and account are provided back.

POST /api/v2/issuers/1234/contracts/1e9802ae-68db-467b-8610-ae59f0d37291/add-cards-accounts?newResourcesOnly=true

Request data

{
   "  ""customers":" "[
      "                           "{
         "            ""requestCorrelationId":" ""117",
         "            ""issuerCustomerExternalReference":" ""PERSON-202212130001C",
         "            ""active":" true",
         "            ""courtesyTitle":" ""Frau",
         "            ""lastName":" ""BOUBOU",
         "            ""firstName":" ""Helen",
         "            ""birthDate":" ""1989-12-20T00:00:00.000Z",
         "            ""birthPlace":" ""Lorch",
         "            ""sex":" ""F",
         "            ""nationality":" ""DE",
         "            ""onlineRiskCategory":"Standard",
         "            ""offlineRiskCategory":"Standard",
         "            ""commercialStatus":"Normal",
         "               ""addresses":" "[
            "                "{
               "                    ""issuerAddressExternalReference":" ""HOME_ADDR_REF_PERSON-202212130001C",
               "                    ""addressLabel":" ""MAIN_POSTAL_ADDRESS",
               "                    ""addressType":" ""POSTAL_MAIL",
               "                    ""postalAddress":" "{
                  "                        ""country":" ""DE",
                  "                        ""line1"" ":" ""HUBERTUSANLAGE 25""                    "
               }"                "
            }"   
            "
         ]"        "
      }"  "
   ],
   "  ""issuerProductExtensionExternalReference":" ""PDT_1234_EXT_VISA_DEBIT_CLASSIC",
   "  ""accountHierarchy":" "{
      "    ""accounts":" "[
         "      "{
            "        ""accountTemplateReference":" ""T_1234_ACC_CHILD_VISA_DEBIT_CLASSIC",
            "         ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212130001C",
            "        ""iban":" ""DE02500105174128973163",
            "        ""accountOwnerRequestCorrelationId":" ""117""      "
         }"    "
      ]"  "
   },
   "  ""cardContracts":" "[
      "    "{
         "      ""card":" "{
            "        ""cardOrder":" "{
               "             ""sendingMode":" ""Normal""        "
            }"      "
         },
         "      ""cardTemplateReference":" ""T_1234_CARD_VISA_DEBIT_CLASSIC",
         "      ""principalSupplementaryCardIndicator":" ""SUPPLEMENTARY",
         "      ""forcedEmbossingName":" ""BOUBOU""    "
      }"  "
   ]
}

Response data

{
   "    ""responseMetadata":" "{
      "        ""correlationId":" ""d4f2ceeb-7e1e-483d-af01-38e630a8e343",
      "        ""statusMessage":" ""Executed successfully",
      "        ""statusCode": 200,
      "        ""responseDateTime":" ""2022-12-13T17:54:15.838+0100",
      "        ""timeTakenMs": 1174 
    
   },
   "    ""data":" "{
      "        ""contract":" "{
         "            ""contractIdentifier":" "{
            "                ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
            "                ""issuerContractExternalReference":" ""CONTRACT-202212130001""            "
         },
         "            ""status":" ""SIGNED",
         "            ""creationDate":" ""2022-12-13T14:40:21.036+00:00",
         "            ""signatureDate":" ""2022-12-13T14:40:21.000+00:00",
         "            ""issuerBranchCode":" ""NO_BRANCH",
         "            ""cardReleaseOrder":" ""AUTOMATIC",
         "            ""productIdentifier":" "{
            "                ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
            "                ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC""            "
         },
         "            ""contractOwnerIdentifier":" "{
            "                ""customerReference":" ""CUS10000351531",
            "                ""issuerCustomerExternalReference":" ""PERSON-202212130001""            "
         },
         "            ""accounts":" "[
            "                "{
               "                    ""accountIdentifier":" "{
                  "                        ""accountReference":" ""12341542264159267791",
                  "                        ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212130001C""                    "
               },
               "                    ""root":" false",
               "                    ""status":" ""ACTIVE",
               "                    ""accountOwnerIdentifier":" "{
                  "                        ""customerReference":" ""CUS10000351533",
                  "                        ""issuerCustomerExternalReference":" ""PERSON-202212130001C""                    "
               },
               "                    ""accountGuarantorIdentifier":" "{
                  "                        ""customerReference":" ""CUS10000351531",
                  "                        ""issuerCustomerExternalReference":" ""PERSON-202212130001""                    "
               }"                "
            }"            "
         ],
         "            ""cardContracts":" "[
            "                "{
               "                    ""cardContractIdentifier":" "{
                  "                        ""cardContractReference":" ""12342000000000380700""                    "
               },
               "                    ""cardHolderIdentifier":" "{
                  "                        ""customerReference":" ""CUS10000351533",
                  "                        ""issuerCustomerExternalReference":" ""PERSON-202212130001C""                    "
               },
               "                    ""status":" ""ACTIVE",
               "                    ""principalSupplementaryCardIndicator":" ""SUPPLEMENTARY",
               "                    ""card":" "{
                  "                        ""cardIdentifier":" "{
                     "                            ""cardReference":" ""2000000000380701""                        "
                  },
                  "                        ""pan":" ""4546176812235324",
                  "                        ""maskedPan":" ""454617******5324",
                  "                        ""expiryDate":" ""1227",
                  "                        ""panSequenceNumber":" ""1",
                  "                        ""status":" ""ACTIVE",
                  "                        ""orders":" "[
                     "                            "{
                        "                                ""orderIdentifier":" "{
                           "                                    ""orderReference":" ""202212132000000000380702""                                "
                        },
                        "                                ""orderType":" ""CardOrder",
                        "                                ""currentInternalStatus":" ""ORDERABLE""                            "
                     }"                        "
                  ],
                  "                        ""panReference":" ""15007c193f2d588f4b8b991ab24537ebe001""                    "
               },
               "                    ""relatedAccounts":" "[
                  "                        "{
                     "                            ""relation":" ""DEFAULT",
                     "                            ""accountIdentifier":" "{
                        "                                ""accountReference":" ""12341542264159267791",
                        "                                ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212130001C""                            "
                     }"                        "
                  }"                    "
               ]"                "
            }"            "
         ]"        "
      },
      "        ""customers":" "[
         "            "{
            "                ""customerIdentifier":" "{
               "                    ""customerReference":" ""CUS10000351533",
               "                    ""issuerCustomerExternalReference":" ""PERSON-202212130001C""                "
            },
            "                ""courtesyTitle":" ""Frau",
            "                ""lastName":" ""BOUBOU",
            "                ""firstName":" ""Helen",
            "                ""addresses":" "[
               "                    "{
                  "                        ""addressIdentifier":" "{
                     "                            ""addressReference":" ""ADDREF_MAIN_POSTAL_ADDRESS_1000000000392075",
                     "                            ""issuerAddressExternalReference":" ""HOME_ADDR_REF_PERSON-202212130001C""                        "
                  },
                  "                        ""addressLabel":" ""MAIN_POSTAL_ADDRESS",
                  "                        ""addressType":" ""POSTAL_MAIL""                    "
               }"                "
            ]"            "
         }"        "
      ]"    "
   }
}

Update Contract

The API allows to update certain data of an existing consumer contract, identified by the Issuer Contract external reference or the Contract reference.

allowed advertisement channels (flags)
allowed data analysis
the issuer branch code (e.g. bank agency in charge of this contract)
allowed delivery channel for possible letters
if the membership fee should be reimbursed when a card contract is closed
how many cards should free of membership fee and/or account setup fee
if the primary card should be considered as the first to be free for membership/account setup fees or if only additional cards should be considered
if both membership and account setup fees should be waived during contract lifecycle (can be changed at any moment)
the membership fee anniversary date can be changed
pass-through data can be updated (specificFields)
content

As a result, the contract is immediately updated with provided data in our system.

Add Cards and Accounts Request

API links

POST /api/v2/issuers/{issuerId}/contracts/{contractReference}/add-cards-accounts

POST /api/v2/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/add-cards-accounts

Below an example of request where the advertisement flags, the delivery channels for correspondence and the branch code are updated for the:

contract reference: 1e9802ae-68db-467b-8610-ae59f0d37291
Issuer: 1234

PATCH /api/v2/issuers/1234/contracts/1e9802ae-68db-467b-8610-ae59f0d37291

Request data

{
   "  ""advertisementFlags":" "{
      "    ""general":" true",
      "    ""email":" false",
      "    ""letter":" false",
      "    ""phone":" false",
      "    ""statement":" true",
      "    ""sms":" false 

  "
   },
   "  ""issuerBranchCode":" ""NO_BRANCH",
   "    ""dataAnalysisFlags":" "{
      "    ""person":" false",
      "    ""paymentTransaction":" false",
      "    ""exchangeThirdParties":" false 

  "
   },
   "  ""deliveryChannel":" "{
      "    ""contractLetterType":" ""LETTER",
      "    ""disputeLetterType":" ""LETTER",
      "    ""statementType":" ""WEB""  "
   }
}

Response data

{
   "    ""responseMetadata":" "{
      "        ""correlationId":" ""25eb44b4-7ff7-41fe-a253-0c2b7519f380",
      "        ""statusMessage":" ""Executed successfully",
      "        ""statusCode": 200,
      "        ""responseDateTime":" ""2022-12-14T18:11:53.053+0100",
      "        ""timeTakenMs": 229 

    
   },
   "    ""data":" "{
      "        ""contractIdentifier":" "{
         "            ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
         "            ""issuerContractExternalReference":" ""CONTRACT-202212130001""        "
      }"    "
   }
}

List Accounts For A Contract

The API allows the list of accounts for a contract, identified by the Issuer Contract external reference or the Contract reference, to be retrieved.

API links

GET /api/v2/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/accounts

GET /api/v2/issuers/{issuerId}/contracts/{contractReference}/accounts

Below an example of request for:

The contract reference: 1e9802ae-68db-467b-8610-ae59f0d37291
The issuer: 1234

The response includes 4 accounts: 1 root account and 3 card accounts.

GET /api/v2/issuers/1234/contracts/1e9802ae-68db-467b-8610-ae59f0d37291/accounts

Response data

{
   "    ""data":" "[
      "        "{
         "            ""issuerId":" ""1234",
         "            ""accountIdentifier":" "{
            "                ""accountReference":" ""12341542264159267791",
            "                ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212130001C""            "
         },
         "            ""root":" false",
         "            ""accountBalance":" "{
            "                ""value": 0,
            "                ""exponent": 2,
            "                ""isoCode":" ""EUR""            "
         },
         "            ""status":" ""ACTIVE",
         "            ""statusDate":" ""2022-12-13T16:54:14.000+00:00",
         "            ""exclusiveCurrency":" false",
         "            ""activationDate":" ""2022-12-13T16:54:14.000+00:00",
         "            ""iban":" ""DE02500105174128973163",
         "            ""name":" ""T_1234_ACC_CHILD_VISA_DEBIT_CLASSIC",
         "            ""workingCurrencyCode":" ""EUR",
         "            ""originalWorkingMode":" ""PAY_NOW",
         "            ""workingMode":" ""PAY_NOW",
         "            ""subscriptionSwitch":" false",
         "            ""toBeSwitched":" false",
         "            ""accountHierarchyReference":" ""12343652199237560111",
         "            ""noGraceOnTheFirstCycle":" false",
         "            ""productIdentifier":" "{
            "                ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
            "                ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC""            "
         },
         "            ""accountProfileReference":" ""P_1234_ACC_CHILD",
         "            ""closureCalendar":" ""C_1234_CLOSURE_DEFAULT",
         "            ""overlimitContribution":" ""0.0",
         "            ""spareChangeSaving":" false",
         "            ""rootAccountIdentifier":" "{
            "                ""accountReference":" ""12343652199237560111",
            "                ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212130001""            "
         },
         "            ""parentAccountIdentifier":" "{
            "                ""accountReference":" ""12343652199237560111",
            "                ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212130001""            "
         },
         "            ""payingAccountIdentifier":" "{
            "                ""accountReference":" ""12341542264159267791",
            "                ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212130001C""            "
         },
         "            ""accountOwnerIdentifier":" "{
            "                ""customerReference":" ""CUS10000351533",
            "                ""issuerCustomerExternalReference":" ""PERSON-202212130001C""            "
         },
         "            ""accountGuarantorIdentifier":" "{
            "                ""customerReference":" ""CUS10000351533",
            "                ""issuerCustomerExternalReference":" ""PERSON-202212130001C""            "
         },
         "            ""contractIdentifier":" "{
            "                ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
            "                ""issuerContractExternalReference":" ""CONTRACT-202212130001""            "
         },
         "            ""delinquent":" false",
         "            ""noOtbCheck":" false",
         "            ""noParentNotification":" false",
         "            ""contractType":" ""CONSUMER",
         "            ""hierarchyOutgoingCreditTransferFeature":" "{
            "                ""periodicOct":" false",
            "                ""octOnContractTerminationAllowed":" false",
            "                ""octOnAccountTerminationAllowed":" false",
            "                ""octOnDemandAllowed":" false 
            "
         }"        "
      },
      "        "{
         "            ""issuerId":" ""1234",
         "            ""accountIdentifier":" "{
            "                ""accountReference":" ""12343652199237560111",
            "                ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212130001""            "
         },
         "            ""root":" true",
         "            ""accountBalance":" "{
            "                ""value": 0,
            "                ""exponent": 2,
            "                ""isoCode":" ""EUR""            "
         },
         "            ""bic":" ""INGDEBB",
         "            ""status":" ""ACTIVE",
         "            ""statusDate":" ""2022-12-13T14:40:21.000+00:00",
         "            ""exclusiveCurrency":" false",
         "            ""activationDate":" ""2022-12-13T14:40:21.000+00:00",
         "            ""iban":" ""DE02500105174128973163",
         "            ""name":" ""T_1234_ACC_ROOT_VISA_DEBIT_CLASSIC",
         "            ""workingCurrencyCode":" ""EUR",
         "            ""originalWorkingMode":" ""PAY_NOW",
         "            ""workingMode":" ""PAY_NOW",
         "            ""subscriptionSwitch":" false",
         "            ""toBeSwitched":" false",
         "            ""accountHierarchyReference":" ""12343652199237560111",
         "            ""originalPaymentMode":" ""CARDHOLDER_DETERMINED",
         "            ""noGraceOnTheFirstCycle":" false",
         "            ""amountDueCalculationLevel":" ""COMPONENT_LEVEL",
         "            ""productIdentifier":" "{
            "                ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
            "                ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC""            "
         },
         "            ""accountProfileReference":" ""P_1234_ACC_ROOT",
         "            ""accountTemplateReference":" ""T_1234_ACC_ROOT_VISA_DEBIT_CLASSIC",
         "            ""closureCalendar":" ""C_1234_CLOSURE_DEFAULT",
         "            ""overlimitContribution":" ""0.0",
         "            ""spareChangeSaving":" false",
         "            ""rootAccountIdentifier":" "{
            "                ""accountReference":" ""12343652199237560111",
            "                ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212130001""            "
         },
         "            ""payingAccountIdentifier":" "{
            "                ""accountReference":" ""12343652199237560111",
            "                ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212130001""            "
         },
         "            ""accountOwnerIdentifier":" "{
            "                ""customerReference":" ""CUS10000351533",
            "                ""issuerCustomerExternalReference":" ""PERSON-202212130001C""            "
         },
         "            ""accountGuarantorIdentifier":" "{
            "                ""customerReference":" ""CUS10000351533",
            "                ""issuerCustomerExternalReference":" ""PERSON-202212130001C""            "
         },
         "            ""contractIdentifier":" "{
            "                ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
            "                ""issuerContractExternalReference":" ""CONTRACT-202212130001""            "
         },
         "            ""delinquent":" false",
         "            ""noOtbCheck":" false",
         "            ""noParentNotification":" false",
         "            ""contractType":" ""CONSUMER",
         "            ""hierarchyOutgoingCreditTransferFeature":" "{
            "                ""periodicOct":" false",
            "                ""octOnContractTerminationAllowed":" false",
            "                ""octOnAccountTerminationAllowed":" false",
            "                ""octOnDemandAllowed":" false 
           "
         }"         "
      },
      "        "{
         "            ""issuerId":" ""1234",
         "            ""accountIdentifier":" "{
            "                ""accountReference":" ""12344689712869894759",
            "                ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212130001B""            "
         },
         "            ""root":" false",
         "            ""accountBalance":" "{
            "                ""value": 0,
            "                ""exponent": 2,
            "                ""isoCode":" ""EUR""            "
         },
         "            ""status":" ""ACTIVE",
         "            ""statusDate":" ""2022-12-13T15:25:57.000+00:00",
         "            ""exclusiveCurrency":" false",
         "            ""activationDate":" ""2022-12-13T15:25:57.000+00:00",
         "            ""iban":" ""DE02500105174128973163",
         "            ""name":" ""T_1234_ACC_CHILD_VISA_DEBIT_CLASSIC",
         "            ""workingCurrencyCode":" ""EUR",
         "            ""originalWorkingMode":" ""PAY_NOW",
         "            ""workingMode":" ""PAY_NOW",
         "            ""subscriptionSwitch":" false",
         "            ""toBeSwitched":" false",
         "            ""accountHierarchyReference":" ""12343652199237560111",
         "            ""noGraceOnTheFirstCycle":" false",
         "            ""productIdentifier":" "{
            "                ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
            "                ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC""            "
         },
         "            ""accountProfileReference":" ""P_1234_ACC_CHILD",
         "            ""closureCalendar":" ""C_1234_CLOSURE_DEFAULT",
         "            ""overlimitContribution":" ""0.0",
         "            ""spareChangeSaving":" false",
         "            ""rootAccountIdentifier":" "{
            "                ""accountReference":" ""12343652199237560111",
            "                ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212130001""            "
         },
         "            ""parentAccountIdentifier":" "{
            "                ""accountReference":" ""12343652199237560111",
            "                ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212130001""            "
         },
         "            ""payingAccountIdentifier":" "{
            "                ""accountReference":" ""12344689712869894759",
            "                ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212130001B""            "
         },
         "            ""accountOwnerIdentifier":" "{
            "                ""customerReference":" ""CUS10000351532",
            "                ""issuerCustomerExternalReference":" ""HOME_ADDR_REF_PERSON-202212130001B""            "
         },
         "            ""accountGuarantorIdentifier":" "{
            "                ""customerReference":" ""CUS10000351533",
            "                ""issuerCustomerExternalReference":" ""PERSON-202212130001C""            "
         },
         "            ""contractIdentifier":" "{
            "                ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
            "                ""issuerContractExternalReference":" ""CONTRACT-202212130001""            "
         },
         "            ""delinquent":" false",
         "            ""noOtbCheck":" false",
         "            ""noParentNotification":" false",
         "            ""contractType":" ""CONSUMER",
         "            ""hierarchyOutgoingCreditTransferFeature":" "{
            "                ""periodicOct":" false",
            "                ""octOnContractTerminationAllowed":" false",
            "                ""octOnAccountTerminationAllowed":" false",
            "                ""octOnDemandAllowed":" false 
            "
         }"        "
      },
      "        "{
         "            ""issuerId":" ""1234",
         "            ""accountIdentifier":" "{
            "                ""accountReference":" ""12343686269046574979",
            "                ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212130001""            "
         },
         "            ""root":" false",
         "            ""accountBalance":" "{
            "                ""value": 0,
            "                ""exponent": 2,
            "                ""isoCode":" ""EUR""            "
         },
         "            ""bic":" ""INGDEBB",
         "            ""status":" ""ACTIVE",
         "            ""statusDate":" ""2022-12-13T14:40:21.000+00:00",
         "            ""exclusiveCurrency":" false",
         "            ""activationDate":" ""2022-12-13T14:40:21.000+00:00",
         "            ""iban":" ""DE02500105174128973163",
         "            ""name":" ""T_1234_ACC_CHILD_VISA_DEBIT_CLASSIC",
         "            ""workingCurrencyCode":" ""EUR",
         "            ""originalWorkingMode":" ""PAY_NOW",
         "            ""workingMode":" ""PAY_NOW",
         "            ""subscriptionSwitch":" false",
         "            ""toBeSwitched":" false",
         "            ""accountHierarchyReference":" ""12343652199237560111",
         "            ""originalPaymentMode":" ""CARDHOLDER_DETERMINED",
         "            ""noGraceOnTheFirstCycle":" false",
         "            ""amountDueCalculationLevel":" ""COMPONENT_LEVEL",
         "            ""productIdentifier":" "{
            "                ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
            "                ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC""            "
         },
         "            ""accountProfileReference":" ""P_1234_ACC_CHILD",
         "            ""accountTemplateReference":" ""T_1234_ACC_CHILD_VISA_DEBIT_CLASSIC",
         "            ""closureCalendar":" ""C_1234_CLOSURE_DEFAULT",
         "            ""overlimitContribution":" ""0.0",
         "            ""spareChangeSaving":" false",
         "            ""rootAccountIdentifier":" "{
            "                ""accountReference":" ""12343652199237560111",
            "                ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212130001""            "
         },
         "            ""parentAccountIdentifier":" "{
            "                ""accountReference":" ""12343652199237560111",
            "                ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212130001""            "
         },
         "            ""payingAccountIdentifier":" "{
            "                ""accountReference":" ""12343686269046574979",
            "                ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212130001""            "
         },
         "            ""accountOwnerIdentifier":" "{
            "                ""customerReference":" ""CUS10000351531",
            "                ""issuerCustomerExternalReference":" ""PERSON-202212130001""            "
         },
         "            ""accountGuarantorIdentifier":" "{
            "                ""customerReference":" ""CUS10000351533",
            "                ""issuerCustomerExternalReference":" ""PERSON-202212130001C""            "
         },
         "            ""contractIdentifier":" "{
            "                ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
            "               ""issuerContractExternalReference":" ""CONTRACT-202212130001""            "
         },
         "            ""delinquent":" false",
         "            ""noOtbCheck":" false",
         "            ""noParentNotification":" false",
         "            ""contractType":" ""CONSUMER",
         "            ""hierarchyOutgoingCreditTransferFeature":" "{
            "                ""periodicOct":" false",
            "                ""octOnContractTerminationAllowed":" false",
            "                ""octOnAccountTerminationAllowed":" false",
            "                ""octOnDemandAllowed":" false 
            "
         }"        "
      }"    "
   ]
}

List Card Contracts For A Contract

The API allows the list of card contract linked to a contract, identified by the Issuer Contract external reference or the Contract reference, to be retrieved.

API links

GET /api/v2/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/card-contracts

GET /api/v2/issuers/{issuerId}/contracts/{contractReference}/card-contracts

Below an example of request for:

The contract reference: 1e9802ae-68db-467b-8610-ae59f0d37291
The issuer: 1234

The response gives 3 card contracts.

GET /api/v2/issuers/1234/contracts/1e9802ae-68db-467b-8610-ae59f0d37291/card-contracts

Response data

{
           "data":" "[
              "        "{
                 "            ""issuerId":" ""1234",
                 "            ""cardContractIdentifier":" "{
                    "                ""cardContractReference":" ""12342000000000380697""            "
                 },
                 "            ""cardTemplateReference":" ""T_1234_CARD_VISA_DEBIT_CLASSIC",
                 "            ""cardTypeCode":" ""F",
                 "            ""status":" ""ACTIVE",
                 "            ""openingDate":" ""2022-12-13T15:25:57.710+00:00",
                 "            ""activationDate":" ""2022-12-13T15:25:57.730+00:00",
                 "            ""trustedAuthenticationReference":" ""123420221213162557294",
                 "            ""newCardRenewalAllowed":" true",
                 "            ""issuerBranchCode":" ""NO_BRANCH",
                 "            ""artwork":" ""DebitClassic",
                 "            ""forcedEmbossingName":" ""BOUBOU",
                 "            ""schemeDeclarationOptOut":" false",
                 "            ""principalSupplementaryCardIndicator":" ""SUPPLEMENTARY",
                 "            ""productCategory":" ""DEBIT",
                 "            ""productCategoryLabel":" ""IMMEDIATE_DEBIT_DEBIT",
                 "            ""productIdentifier":" "{
                    "                ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
                    "                ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC""            "
                 },
                 "            ""cardHolderIdentifier":" "{
                    "                ""customerReference":" ""CUS10000351532",
                    "                ""issuerCustomerExternalReference":" ""HOME_ADDR_REF_PERSON-202212130001B""            "
                 },
                 "            ""vipFlag":" false",
                 "            ""contractIdentifier":" "{
                    "                ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
                    "                ""issuerContractExternalReference":" ""CONTRACT-202212130001""            "
                 },
                 "            ""cardProfileDescription":" ""P_1234_CARD_VISA_DEBIT_CLASSIC",
                 "            ""cardProfileReference":" ""P_1234_CARD_VISA_DEBIT_CLASSIC""        "
              },
              "        "{
                 "            ""issuerId":" ""1234",
                 "            ""cardContractIdentifier":" "{
                    "                ""cardContractReference":" ""12342000000000380694",
                    "                ""issuerCardContractExternalReference":" ""CARD_CONTRACT-202212130001""            "
                 },
                 "            ""cardTemplateReference":" ""T_1234_CARD_VISA_DEBIT_CLASSIC",
                 "            ""cardTypeCode":" ""F",
                 "            ""status":" ""ACTIVE",
                 "            ""openingDate":" ""2022-12-13T14:40:21.527+00:00",
                 "            ""activationDate":" ""2022-12-13T14:40:21.527+00:00",
                 "            ""trustedAuthenticationReference":" ""123420221213154021607",
                 "            ""newCardRenewalAllowed":" true",
                 "            ""issuerBranchCode":" ""NO_BRANCH",
                 "            ""artwork":" ""DebitClassic",
                 "            ""forcedEmbossingName":" ""BOUBOU*TEST BOUBOU EMBOSS2",
                 "            ""schemeDeclarationOptOut":" false",
                 "            ""principalSupplementaryCardIndicator":" ""SUPPLEMENTARY",
                 "            ""productCategory":" ""DEBIT",
                 "            ""productCategoryLabel":" ""IMMEDIATE_DEBIT_DEBIT",
                 "            ""productIdentifier":" "{
                    "                ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
                    "                ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC""            "
                 },
                 "            ""cardHolderIdentifier":" "{
                    "                ""customerReference":" ""CUS10000351531",
                    "                ""issuerCustomerExternalReference":" ""PERSON-202212130001""            "
                 },
                 "            ""contractIdentifier":" "{
                    "                ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
                    "                ""issuerContractExternalReference":" ""CONTRACT-202212130001""            "
                 },
                 "            ""cardProfileDescription":" ""P_1234_CARD_VISA_DEBIT_CLASSIC",
                 "            ""cardProfileReference":" ""P_1234_CARD_VISA_DEBIT_CLASSIC""        "
              },
              "        "{
                 "            ""issuerId":" ""1234",
                 "            ""cardContractIdentifier":" "{
                    "                ""cardContractReference":" ""12342000000000380700""            "
                 },
                 "            ""cardTemplateReference":" ""T_1234_CARD_VISA_DEBIT_CLASSIC",
                 "            ""cardTypeCode":" ""F",
                 "            ""status":" ""ACTIVE",
                 "            ""openingDate":" ""2022-12-13T16:54:15.002+00:00",
                 "            ""activationDate":" ""2022-12-13T16:54:15.112+00:00",
                 "            ""trustedAuthenticationReference":" ""123420221213175415246",
                 "            ""newCardRenewalAllowed":" true",
                 "            ""issuerBranchCode":" ""NO_BRANCH",
                 "            ""artwork":" ""DebitClassic",
                 "            ""forcedEmbossingName":" ""BOUBOU",
                 "            ""schemeDeclarationOptOut":" false",
                 "            ""principalSupplementaryCardIndicator":" ""PRINCIPAL",
                 "            ""productCategory":" ""DEBIT",
                 "            ""productCategoryLabel":" ""IMMEDIATE_DEBIT_DEBIT",
                 "            ""productIdentifier":" "{
                    "                ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC",
                    "                ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC""            "
                 },
                 "            ""cardHolderIdentifier":" "{
                    "                ""customerReference":" ""CUS10000351533",
                    "                ""issuerCustomerExternalReference":" ""PERSON-202212130001C""            "
                 },
                 "            ""contractIdentifier":" "{
                    "                ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
                    "                ""issuerContractExternalReference":" ""CONTRACT-202212130001""            "
                 },
                 "            ""cardProfileDescription":" ""P_1234_CARD_VISA_DEBIT_CLASSIC",
                 "            ""cardProfileReference":" ""P_1234_CARD_VISA_DEBIT_CLASSIC""        "
              }"    "
           ]
        }

Suspend A Contract

The API allows a contract, identified by the Issuer Contract external reference or the Contract reference, to be suspended.

It is possible to indicate whether membership/account setup fees must be partially reimbursed with the contract suspension.

The contract suspension has the following effects:

The contract closure is scheduled according to a delay configurable at issuer level
Immediate temporary card blocking
Renewal and replacement of all cards blocking
Account Setup Fee and Membership Fee are suppressed.
An Outgoing Credit Transfer (OCT) is automatically generated if the account has a credit balance.

API links

POST /api/v2/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/suspend

POST /api/v2/issuers/{issuerId}/contracts/{contractReference}/suspend

Cancel A Contract Suspension

As long as the closure date is not reached, contract suspension can be removed.

The contract suspension cancellation has the following effects:

The scheduled contract closure date is removed
Renewal is unblocked
Replacement is unblocked
Cards linked to the contract are unblocked

The API allows a contract suspension process to be cancelled.

The contract is identified by the Issuer Contract external reference or the Contract reference.

API links

POST /api/v2/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/cancel-suspend

POST /api/v2/issuers/{issuerId}/contracts/{contractReference}/cancel-suspend

Close Contract

The API allows a contract, identified by the Issuer Contract external reference or the Contract reference, to be closed.

The contract can be closed immediately, scheduled to be closed at a date provided by the issuer or set to be closed at the card expiry date.

The contract must not be closed or awaiting signature.

As a result:

For immediate closure: the contract is closed, the cards within the contract are deactivated (next authorizations are declined), the closure is triggered for the accounts.
For scheduled closure: the contract is not changed until the closing date is reached. Once the closing date is reached, the contract is closed, the cards within the contract are deactivated, the closure is triggered for the accounts.

API links

POST /api/V2/issuers/{issuerId}/contracts/{contractReference}/close

POST /api/V2/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/close

Below an example of request with a scheduled closure date:

contract reference: 4459f986-5242-4202-9ed5-f652573e9f63
issuer: 1234

POST api/v2/issuers/1234/contracts/4459f986-5242-4202-9ed5-f652573e9f63/close

Request data

{
                           "  ""closingComment":" ""closingContract",
                           "  ""closingDate":" ""2023-04-30T02:31:44.650Z",
                           "  ""closingReason":" ""EXPIRED",
                           "  ""closureDelayType":" ""SCHEDULED"
                        }

Response data

{
                           "    ""responseMetadata":" "{
                              "        ""correlationId":" ""65aa7f43-b3d2-4160-927e-95801efad125",
                              "        ""statusMessage":" ""Executed successfully",
                              "        ""statusCode": 200,
                              "        ""responseDateTime":" ""2023-02-02T15:52:38.281+0100",
                              "        ""timeTakenMs": 450 
                            
                           },
                           "    ""data":" "{
                              "        ""contract":" "{
                                 "            ""contractIdentifier":" "{
                                    "                ""contractReference":" ""4459f986-5242-4202-9ed5-f652573e9f63",
                                    "                ""issuerContractExternalReference":" ""CONTRACT-202212050001""            "
                                 },
                                 "            ""status":" ""SIGNED",
                                 "            ""closingDate":" ""2023-04-30T02:31:44.650+00:00",
                                 "            ""accounts":" "[
                                    "                "{
                                       "                    ""accountIdentifier":" "{
                                          "                        ""accountReference":" ""65008505533653587133",
                                          "                        ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212050001""                    "
                                       },
                                       "                    ""root":" false",
                                       "                    ""status":" ""ACTIVE""                "
                                    },
                                    "                "{
                                       "                    ""accountIdentifier":" "{
                                          "                        ""accountReference":" ""65006621070985963583",
                                          "                        ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212050001""                    "
                                       },
                                       "                    ""root":" true",
                                       "                    ""status":" ""ACTIVE""                "
                                    },
                                    "                "{
                                       "                    ""accountIdentifier":" "{
                                          "                        ""accountReference":" ""65009389899134164294",
                                          "                        ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212050001B""                    "
                                       },
                                       "                    ""root":" false",
                                       "                    ""status":" ""ACTIVE""                "
                                    }"            "
                                 ],
                                 "            ""cardContracts":" "[
                                    "                "{
                                       "                    ""cardContractIdentifier":" "{
                                          "                        ""cardContractReference":" ""65002000000000374459""                    "
                                       },
                                       "                    ""status":" ""ACTIVE",
                                       "                    ""cards":" "[
                                          "                        "{
                                             "                            ""cardIdentifier":" "{
                                                "                                ""cardReference":" ""2000000000374460""                            "
                                             },
                                             "                            ""maskedPan":" ""454617******2386",
                                             "                            ""expiryDate":" ""1227",
                                             "                            ""panSequenceNumber":" ""1",
                                             "                            ""status":" ""BLOCKED""                        "
                                          }"                    "
                                       ]"                "
                                    },
                                    "                "{
                                       "                    ""cardContractIdentifier":" "{
                                          "                        ""cardContractReference":" ""65002000000000374437""                    "
                                       },
                                       "                    ""status":" ""ACTIVE",
                                       "                    ""cards":" "[
                                          "                        "{
                                             "                            ""cardIdentifier":" "{
                                                "                                ""cardReference":" ""2000000000374438",
                                                "                                ""issuerCardExternalReference":" ""CARD-202212050001""                            "
                                             },
                                             "                            ""maskedPan":" ""454617******6413",
                                             "                            ""expiryDate":" ""1227",
                                             "                            ""panSequenceNumber":" ""1",
                                             "                            ""status":" ""ACTIVE""                        "
                                          }"                    "
                                       ]"                "
                                    }"            "
                                 ]"        "
                              }"    "
                           }
                        }

Cancel A Contract Closing

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

The main input fields are:

The issuer ID
The issuer contract external reference or the contract reference

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

API links

POST /api/v2/issuers/{issuerId}/contracts/{contractReference}/cancel-close

POST /api/v2/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/cancel-close

Below an example of request with a scheduled closure date:

contract reference: 4459f986-5242-4202-9ed5-f652573e9f63
issuer: 1234

POST /api/v2/issuers/1234/contracts/4459f986-5242-4202-9ed5-f652573e9f63/cancel-close

Response data

{
           "    ""responseMetadata":" "{
              "        ""correlationId":" ""3e657247-7ff1-4a1c-b590-6180fb10f353",
              "        ""statusMessage":" ""Executed successfully",
              "        ""statusCode": 200,
              "        ""responseDateTime":" ""2023-02-02T16:35:32.795+0100",
              "        ""timeTakenMs": 81 
            
           },
           "    ""data":" "{
              "        ""contractIdentifier":" "{
                 "            ""contractReference":" ""4459f986-5242-4202-9ed5-f652573e9f63",
                 "            ""issuerContractExternalReference":" ""CONTRACT-202212050001""        "
              }"    "
           }
        }

List Contract Fees For A Contract

The API allows the list of contract fees linked to a contract, identified by the Issuer Contract external reference or the Contract reference, to be retrieved.

In response, the model references are provided for each account part of the contract.

API links

GET /api/v2/issuers/{issuerId}/contracts/{contractReference}/contract-fees

GET /api/v2/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/contract-fees

Here, an example of request for:

The contract reference: 1f798c05-f18b-4e6d-9ce3-017d6de43b92
The issuer: 1234

The response gives membership fee model applied to the card account “12349288360035054578”.

GET /api/v2/issuers/1234/contracts/1f798c05-f18b-4e6d-9ce3-017d6de43b92/contract-fees

Response data

{
   "    ""data":" "[
      "        "{
         "            ""accountIdentifier":" "{
            "                ""accountReference":" ""12344084403017969976",
            "                ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212160001""            "
         }"        "
      },
      "        "{
         "            ""accountIdentifier":" "{
            "                ""accountReference":" ""12349288360035054578",
            "                ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212160001""            "
         },
         "            ""selectedModels":" "[
            "                "{
               "                    ""reference":" ""M_1234_ACCSETUPFEE_GOLD_41",
               "                    ""type":" ""ACCOUNT_SETUP_FEE""                "
            },
            "                "{
               "                    ""reference":" ""M_1234_MEMBERSHIPFEE_GOLD_41",
               "                    ""type":" ""MEMBERSHIP_FEE""                "
            }"            "
         ]"        "
      }"    "
   ]
}

Update Contract Fees For A Given Contract And Card Account

This API enables the contract fees (Membership fee and account set-up fee) to be updated for a given contract and given card account in the contract.

This is done by providing in input the new model reference and the type to be used.

This model has to be configured previously for the product.

API links

PATCH /api/v2/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/contract-fees/{accountReference}

PATCH /api/v2/issuers/{issuerId}/contracts/{contractReference}/contract-fees/{accountReference}

PATCH /api/v2/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/contract-fees/external-accounts/{issuerAccountExternalReference}

Here, an example of request for:

The contract reference: 1f798c05-f18b-4e6d-9ce3-017d6de43b92
The issuer: 1234
The account 12349288360035054578

The response updates the membership fee model applied to the card account “12349288360035054578”.

PATCH /api/v2/issuers/1234/contracts/1f798c05-f18b-4e6d-9ce3-017d6de43b92/contract-fees/12349288360035054578

Request data

{
   "  ""selectedModels":" "[
      "    "{
         "      ""reference":" ""M_1234_MEMBERSHIPFEE_GOLD_21",
         "      ""type":" ""MEMBERSHIP_FEE""    "
      }"  "
   ]
}

Response data

{
   "    ""responseMetadata":" "{
      "        ""correlationId":" ""29a7a912-b795-4cc1-a831-7d872128015a",
      "        ""statusMessage":" ""Executed successfully",
      "        ""statusCode": 200,
      "        ""responseDateTime":" ""2022-12-16T17:28:18.502+0100",
      "        ""timeTakenMs": 317 
    
   },
   "    ""data":" "{
      "        ""accountIdentifier":" "{
         "            ""accountReference":" ""12349288360035054578",
         "            ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212160001""        "
      }"    "
   }
}

Retrieve Contract Owner A Contract

This API allows the contract owner for a contract identified by the Issuer Contract external reference or the Contract reference, to be retrieved.

API links

GET /api/v2/issuers/{issuerId}/contracts/{contractReference}/contract-owner

Here, an example of request for:

The contract reference: 1e9802ae-68db-467b-8610-ae59f0d37291
The issuer: 1234

GET /api/v2/issuers/1234/contracts/1e9802ae-68db-467b-8610-ae59f0d37291/contract-owner

Response data

{
   "    ""data":" "{
      "        ""issuerId":" ""1234",
      "        ""customerIdentifier":" "{
         "            ""customerReference":" ""CUS10000351533",
         "            ""issuerCustomerExternalReference":" ""PERSON-202212130001C""        "
      },
      "        ""active":" true",
      "        ""birthDate":" ""1989-12-20T00:00:00.000+00:00",
      "        ""birthPlace":" ""Lorch",
      "        ""commercialStatus":" ""Normal",
      "        ""courtesyTitle":" ""Frau",
      "        ""firstName":" ""Helen",
      "        ""lastName":" ""BOUBOU",
      "        ""monthlySalary":" ""0",
      "        ""nationality":" ""DE",
      "        ""offlineRiskCategory":" ""Standard",
      "        ""onlineRiskCategory":" ""Standard",
      "        ""sex":" ""F""    "
   }
}

Switch Between Principal And Supplementary Cards

The API is used to change the contract owner of the main card by a cardholder of an additional card belonging to the same contract.

The API requires in input:

the Issuer ID
the contract reference
the cardholder reference (future contract owner and future cardholder of the main card)
the card contract reference (optional - in case the cardholder has several card contracts in different contracts)

In return, the list of all changes is provided at contract level and card contracts level (old main card and new main card).

API links

POST /api/V2/issuers/{issuerId}/contracts/{contractReference}/switch-principal-card

POST /api/V2/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/switch-principal-card

Below an example of the switch request for

Contract reference: 1e9802ae-68db-467b-8610-ae59f0d37291
Customer reference: CUS10000351533

POST /api/v2/issuers/1234/contracts/1e9802ae-68db-467b-8610-ae59f0d37291/switch-principal-card

Request data

{ 
        "cardHolderIdentifier": { 
            "customerReference": "CUS10000351533" 
          } 
        }

Response data

{
           " ""responseMetadata":" "{
              "        ""correlationId":" ""adae8262-0114-4221-8bd4-305be87e2f89",
              "        ""statusMessage":" ""Executed successfully",
              "        ""statusCode": 200,
              "        ""responseDateTime":" ""2022-12-14T12:49:33.884+0100",
              "        ""timeTakenMs": 1138 
            
           },
           "    ""data":" "{
              "        ""contract":" "{
                 "            ""contractIdentifier":" "{
                    "                ""contractReference":" ""1e9802ae-68db-467b-8610-ae59f0d37291",
                    "                ""issuerContractExternalReference":" ""CONTRACT-202212130001""            "
                 },
                 "            ""contractOwnerIdentifier":" "{
                    "                ""customerReference":" ""CUS10000351533",
                    "                ""issuerCustomerExternalReference":" ""PERSON-202212130001C""            "
                 },
                 "            ""cardContracts":" "[
                    "                "{
                       "                    ""cardContractIdentifier":" "{
                          "                        ""cardContractReference":" ""12342000000000380700""                    "
                       },
                       "                    ""principalSupplementaryCardIndicator":" ""PRINCIPAL""                "
                    },
                    "                "{
                       "                    ""cardContractIdentifier":" "{
                          "                        ""cardContractReference":" ""12342000000000380694",
                          "                        ""issuerCardContractExternalReference":" ""CARD_CONTRACT-202212130001""                    "
                       },
                       "                    ""principalSupplementaryCardIndicator":" ""SUPPLEMENTARY""                "
                    }"            "
                 ]"        "
              }"    "
           }
        }

List Legitimacy Documents For A Contract

Legitimacy documents correspond to documents that prove the identity of a customer (pass ID, national card ID)

The document type, The document ID, the expiry date of the document, its issuing date can be stored in our system.

This API is used to get the customers legitimacy documents of a contract.

The input parameters are:

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

API links

GET /api/v2/issuers/{issuerId}/contracts/{contractReference}/legitimacy-documents

GET /api/v2/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/legitimacy-documents

Below an example of request for:

The contract reference: 1e9802ae-68db-467b-8610-ae59f0d37291

For this contract, there are 2 customers. The response gives the legitimacy documents for each of them.

GET /api/v2/issuers/1234/contracts/1e9802ae-68db-467b-8610-ae59f0d37291/legitimacy-documents

Response data

{
   {
      "    ""data":" "[
         "        "{
            "            ""legitimacyDocumentType":" ""Passport",
            "            ""legitimacyDocumentId":" ""7845128",
            "            ""legitimacyDocumentDate":" ""2020-07-25T00:00:00.000+00:00",
            "            ""legitimacyDocumentExpiryDate":" ""2020-07-25T00:00:00.000+00:00",
            "            ""legitimated":" true",
            "            ""customerIdentifier":" "{
               "                ""customerReference":" ""CUS10000351532",
               "                ""issuerCustomerExternalReference":" ""PERSON-202212130001B""            "
            }"        "
         },
         "        "{
            "            ""legitimacyDocumentType":" ""Passport",
            "            ""legitimacyDocumentId":" ""9512345",
            "            ""legitimacyDocumentDate":" ""2016-10-13T00:00:00.000+00:00",
            "            ""legitimacyDocumentExpiryDate":" ""2026-10-13T00:00:00.000+00:00",
            "            ""legitimated":" true",
            "            ""customerIdentifier":" "{
               "                ""customerReference":" ""CUS10000351531",
               "                ""issuerCustomerExternalReference":" ""PERSON-202212130001""            "
            }"        "
         }"    "
      ]
   }

The contract reference: 1e9802ae-68db-467b-8610-ae59f0d37291

Update Legitimacy Document Of A Contract Customer

This API is used to update the customers legitimacy documents of a contract.

The input parameters are:

the contract and the customer identifier for which information must be updated.

They can be provided by using the internal references or the issuer external references:

contract reference and customer reference or
issuer contract external reference and issuer customer external reference

API links

POST /api/v2/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/legitimacy-documents/external-customers/{issuerCustomerExternalReference}

POST /api/v2/issuers/{issuerId}/contracts/{contractReference}/legitimacy-documents/{customerReference}

Below an example of request for:

the contract reference: 1e9802ae-68db-467b-8610-ae59f0d37291
the customer reference: CUS10000351531

POST /api/v2/issuers/1234/contracts/1e9802ae-68db-467b-8610-ae59f0d37291/legitimacy-documents/CUS10000351531

Request data

  { 
          "legitimacyDocumentType": "Passport", 
          "legitimacyDocumentId": "9512345", 
          "legitimacyDocumentDate": "2016-10-13T00:00:00.000Z", 
          "legitimacyDocumentExpiryDate": "2026-10-13T00:00:00.000Z", 
          "legitimated": true 
        }

Response data

{
           "responseMetadata":{
              "correlationId":"351096b5-98ce-409b-b01d-daa77ff6f5be",
              "statusMessage":"Executed successfully",
              "statusCode":200,
              "responseDateTime":"2022-12-13T16:35:02.551+0100",
              "timeTakenMs":148
           },
           "data":{
              "legitimacyDocumentType":"Passport",
              "legitimacyDocumentId":"9512345",
              "legitimacyDocumentDate":"2016-10-13T00:00:00.000+00:00",
              "legitimacyDocumentExpiryDate":"2026-10-13T00:00:00.000+00:00",
              "legitimated":true
           }
        }

Sign A Contract

The API allows to:

sign a contract, identified by the Issuer Contract external reference or the Contract reference (the contract must be in "awaiting signature" status)
request to activate all cards within this contract simultaneously

As a result:

the contract is signed
the accounts within the contract are activated
the cards within the contract are activated if requested
the contract can be updated

API links

POST /api/v2/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/sign

POST /api/v2 /issuers/{issuerId}/contracts/{contractReference}/sign

Replace A Customer Within A Consumer Contract

The API can be used to replace a customer belonging to a consumer contract, by an existing one in our system or by a new one.

The customer to be replaced can be the contract owner, the account owner, the cardholder, etc...of the contract.

The main input fields are:

The issuer ID
The issuer contract external reference or the contract reference
The issuer customer external reference or the customer reference for which the replacement is requested
The target customer (by providing either the issuer customer external reference or the customer reference) if the customer already exists in our system, or a new one

In return, the API provides the identifiers of all customers (contract owner account owner, the cardholder, etc...) associated to the consumer contract.

API links

POST /api/v2/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}replace-customer

POST /api/v2 /issuers/{issuerId}/contracts/{contractReference}/replace-customer

Refund fee on demand

The API is used to trigger an on demand pro rata refund of Account Setup (AS) fee or Membership fee (MS) for the unutilized period.

Pre Conditions:

In case refund for Account Setup fee is requested then card contract closure date should be less than card contract creation date + 1 year
In case refund for Membership fee is requested, then the Membership fee should already be posted
Account setup fee refund on demand can be received only once during contract lifecycle
Membership fee refund on demand can be received only once between Membership fee anniversary dates

The issuer can request the refund by AS or MS fee by providing:

The fee type: Either Account Setup fee or Membership Fee
Card Contract Reference

As a Result:

For Account Setup fee:
- If account is in closed status (BEING_CLOSED), the pro rata refund will be calculated and posted with the following logic: Posted AS fee amount * (Number of days from contract cancellation till (card contract creation + 1 year) / number of days in the year),
- In other cases, it will be calculated in the following logic:,Posted AS fee amount * (Number of days from the date when demand for refund is received till (card contract creation + 1 year) / number of days in the year)
For Membership Fee:
- If account is in closed status (BEING_CLOSED), the pro rata refund will be calculated and posted with the following logic: MS fee posted on last MS fee anniversary date * (Number of days from contract cancellation till next MS Fee Anniversary date / number of days in the year)
- In other cases, it will be calculated in the following logic: MS fee posted on last MS fee anniversary date * (Number of days from the date when demand for refund is received till next MS Fee Anniversary date / number of days in the year).

API links

POST /api/v2/issuers/{issuerId}/contract/{contractReference}/refundFeeOnDemand

POST /api/v2/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/refundFeeOnDemand

Search Contracts By criteria (multi-issuers)

The API provides possibility to retrieve a list of consumer contracts, based on certain criteria.

One of the following criteria for searching must be provided:

either account's criteria
or customer's criteria
or card's criteria

For searching with account's criteria, only one of the following data must be provided :

IBAN
or account identifier : either account reference or issuer account external reference
or account membership number 1
or account membership number 2

For searching with customer's criteria, only one of the following data must be provided :

Personal Data with last name and first name (and optionally with birth date, postal address : postal code, street name and/or building number, phonetic criteria)
or customer identifier : either customer reference or issuer customer external reference
or partner external reference

For searching with card's criteria, only one of the following data must be provided :

PAN
or card contract identifier : either card contract reference or issuer card contract external reference
or card identifier : either card reference or issuer card external reference

If requested, the API input parameters allows also to:

search from an issuer and optionally with sub-issuers OR search from a list of issuers (by default, the search is performed on all issuers allowed for the user depending on its rights)
limit the list of returned cards per card contract to either the latest card only or all previous cards
return the direct parent account in the hierarchy of the account and/or the list of child accounts of the account matching the criteria if the research is based on account's criteria
request to enrich the response with additional data relative to the accounts, the card contracts, the cards and the customers by using embedded fields

The API response contains all matched contracts and for each returned contract some information is provided such as :

contract identifier with the contract reference, the issuer external contract reference if originally provided
product change information if any, such as its current status, new product, new contract if it exists
embedded fields if requested such as list of all customers or identifiers linked to this contract (e.g. contract owner, root account owner, cardholder(s)), accounts and account identifiers, card contracts, cards

API links

POST /api/v2/search-contracts

Subscribe to add-on

The API allows a cardholder to subscribe to an additional service (e.g. new letter, travel insurance) for the contract during all contract life cycle

The list of allowed additional services are defined on the product (e.g. PORTAL_ACCESS, ALERT, NOTIFICATION).

The main input fields requested by the API are:

The issuer ID
The contract for which the add-on subscription is requested: It can be provided by using the contract reference or the issuer external contract reference
The identifier of the entity for which the add-on subscription is requested: Either the card contract by providing the card contract reference or the issuer external card contract reference, OR the account by providing the account reference or the issuer external account reference
The corresponding reference of the additional service
The service type reference defined at product level

Depending on the service type, the issuer can add additional parameters to the add-on service.

As a result:

The new add-on subscription for the contract is available and can be unsubscribed during all contract life cycle
A fee can be generated and posted to the cardholder account if required for the product.

API links

POST /api/v2/issuers/{issuerId}/contracts/{contractReference}/addon-subscriptions

POST /api/v2/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/addon-subscriptions

Unsubscribe to add-on

The API allows a cardholder to unsubscribe from an additional service (e.g. new letter, travel insurance) for the contract during all contract life cycle.

The main input fields requested by the API are:

The issuer ID
The contract for which the add-on unsubscription is requested: It can be provided by using the contract reference or the issuer external contract reference
The identifier of the entity for which the add-on unsubscription is requested: Either the card contract by providing the card contract reference or the issuer external card contract reference, OR the account by providing the account reference or the issuer external account reference
The corresponding reference of the additional service
The service type reference

As a result, the existing add-on subscription for the contract is no longer available.

API links

POST /api/v2/issuers/{issuerId}/contracts/{contractReference}/addon-subscriptions/unsubscribe

POST /api/v2/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/addon-subscriptions/unsubscribe

Retrieve the list of add-on services

The API allows the list of additional service subscriptions (e.g. new letter, travel insurance) for the contract to be retrieved.

The main input fields requested by the API are:

The issuer ID
The contract for which the add-on subscriptions are requested: It can be provided by using the contract reference or the issuer external contract reference

The API response contains add-on subscription information such as:

The reference of the additional service subscription
The service type reference
The card contract or the account on which the subscription has been done
The date of subscription to the add-on service
The list of add-on service parameters if any

API links

GET /api/v2/issuers/{issuerId}/contracts/{contractReference}/addon-subscriptions

GET /api/v2/issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/addon-subscriptions

Advice a product extension

This API is used to get the product extension for a card creation depending on the configured algorithm. It can be used for the first card or additional card.

The main input fields are:

The issuer ID
The issuer product external reference for which the advice is requested.

The API returns the product extension advised for the card creation.

API links

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

ob-p-ideal-debtor-preference

Read more about ob-p-ideal-debtor-preference

Debtor preference retrieval API

API Reference

Get Preferences

Endpoint: Get /preferences/{Psuid}

This API can be used to retrieve the iDEAL preferences of a PSU. This will only work after an initial payment by this PSU was successfully completed. More details about the fields can be found in the API reference.

Data model

Legend

Orange fields: mandatory for iDEAL preferences
Purple fields: optional for iDEAL preferences

Request

Response

Example

Request (Signature-related fields "Digest" and "Signature" are conditionally mandatory):

Address: https://localhost:8443/xs2a/routingservice/services/ob/pis/v3/preferences/896587495-51254-85475893254
    HttpMethod: GET
    Headers: {Accept=application/json, AspspId=10002, Digest=SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=, X-Request-ID=08cc7007-f3c4-6586-4449-8dbf7a92740b, Authorization=Bearer 788b75b7ea27116c74d4a271404c5f49074fbc786ae67cf771a3a44a02a387d8, MessageCreateDateTime=2023-03-15T13:16:40.448Z, Signature=keyId="8D0F688AD3E6C2D4D5FB99FE129F2A2E3B496AF7",algorithm="SHA256withRSA",headers="digest x-request-id messagecreatedatetime (request-target)",signature="hjSmi6wuf/FTDyJ5W7F7QnzDj2X1KVjYuy5hbig+gF6JBhxBfJtZT4utnBgw6OG9dPyqB0EYHPJby786k+q44kl+pWMPJWAJjNHeXyNufNDENF3GGsRsnqBjwrNp9575vsIeimG34A6x47Ap1/01Nmsqk4NzGr0F0HAVyIbeX0Q9oKd6MJHBaswkv9nqaQTajIpmdesAA5D6eNTSfz4oBOCgk2FlJpUAdaAg9Nd1uZuXV+Jeug2coU+jc5FZUQXyZRaV7hiE5UtBIQVxpml6aydFZwCD6OaRJrGvluebVprYc1bqSsiMmS4Pk+qDJshSk5cWWhnp/bVsUFIIK+NU3g=="}

Response (Signature-related fields "Digest" and "Signature" are conditionally present):

ResponseCode: 200
 
    Headers: {X-Request-ID=2db64c57-fc84-4998-a83c-aa33ff7fbd9b, MessageCreateDateTime=2023-03-15T13:16:40.898Z, Digest=SHA-256=bd7zfJ14uHY5YwvcXpqr78Df5jUpb0Z64styUET3afI=, Signature=keyId="3EBEF6033C00730D9C6DA05165A3CAA1F31036FB",algorithm="rsa-sha256",headers="messagecreatedatetime x-request-id digest",signature="kBpt9O2Auydz0398VFDf0M9lVWcGVI8CsNJbpvAcXxtmTnlO9cH2MlqZQqlMHGjDqcOMmjGeELaQLAft/R1p8HQoyIMJRxh9PtauyKTnHqLavLj6bJr4BoEUeQpE+xfXaR3tebVWz6zr+c7guHEqDjfNKaoKs5HjQIMm/qjKaptU7zkTCIiFsTWh0tmy/h+biI3MJzxqwpZcGdlOCgJ0LI1squZaQXmgA+AsC+uOomBgyhBMPRxMiFIyYPKnA3Ev+UL7UEm3F49B4d/AWYyO2E6B+9p470eA4Ippc4PHeBGvdNgX6zKERsDhCM8ZTmWlOeBh3i5QWvpJF/5Kv6qYHA==",  Date=Wed, 15 Mar 2023 13:16:40 GMT}
    Payload: {
    "AspspName": "IssuerName",
    "AspspLogoUrl": "https://checkout.company.com/login",
    "DebtorAccountIdentification": "NL44RABO******6789"
}

ob-p-ideal-pis-api

Read more about ob-p-ideal-pis-api

Payment Initiation API

for iDEAL 2.0

API Reference

The iDEAL payment api uses a subset of the available open banking API's. In this chapter only the api's needed for iDEAL payment initiation are described, furthermore the fields applicable to an iDEAL payment are marked purple (optional) and orange (mandatory).

Payment Status

Payments have different status depending on the actual state of processing:

Open
SettlementCompleted
Cancelled
Expired
Error

In the following picture the possible iDEAL status are shown in an activity diagram:

POST Payments

Endpoint: POST /payments

The base URL for the payment initiation service API is: /xs2a/routingservice/services/ob/pis/v3

This endpoint is used by the Initiating Party to make an iDEAL 2.0 payment request towards the Open Banking Service.

Information

During a prolonged period the Initiating Party is allowed to use the CommonPaymentData.DebtorInformation.Agent field to pass a BIC which identifies the ASPSP. This is done to facilitate a smooth migration from iDEAL to iDEAL 2.0.

When the CommonPaymentData.DebtorInformation.Agent field is filled the response will always have a RedirectUrl which redirects directly to the ASPSP.

This feature is only available if FlowType = standard and no iDEAL Debtor token is used.
This feature will be discontinued and is only meant to be used during the migration period.

Data model

Legend

Orange fields: mandatory for an iDEAL payment
Purple fields: conditionally mandatory for an iDEAL payment

Request (click to enlarge)

Response (click to enlarge)

Example: Standard iDEAL payment without Debtor token

Request (Signature-related fields "Digest" and "Signature" are conditionally mandatory):

Address: https://digitalroutingservice.awltest.de/xs2a/routingservice/services/ob/pis/v3/payments
    HttpMethod: POST
    Content-Type: application/json; charset=UTF-8
    ExchangeId: b02d7597-3109-4291-86c3-a1d7faaee11c
    Headers: {Accept=application/json, Digest=SHA-256=0P2tSst5wZ/1rBS+ZF5Pvp79klNUek7tetk0j9w+mNs=, X-Request-ID=fd3a9dae-5323-ea5a-5460-48857a264b9d, Authorization=Bearer 55aefa2dbd728d28dce18ef04e12e7014cde1e665901bc55ae0be044f114001e, MessageCreateDateTime=2023-12-29T16:38:45.770Z, Signature=keyId="39d8e82bb33e7e2a09cbcb3ef3eab351ee1c5e8f",algorithm="SHA256withRSA",headers="x-request-id (request-target) digest messagecreatedatetime",signature="a94S2WkCTBMdzx3nZrDcA61YkAsesjR9BjKkwvGLEmsCPyEUqk55zYHHE0rLVHwVD7YNchMZnEWFR3Vf63egGSTMPTD0xfmHZJua7Wz/VZVpmIkckCjfYiaQTilVImTcKeBIjhnkAd7MP2qQkr6bDtyQQ1zy1DGwDQgTlNVxOHbv+WcMKJxoQcFn5qLTvaq6fnat3a2Ka/jAUHRytAJ+5xWRT0tKq85LvjB10fho8gMgHQ+4q/0H2gmPhh9QYDwCawbBdgdDWb5HtX0qjhftO3iAb4G5HOlrqSBdTprYVDJmtqwh3YEekfy8KyHifiMMWiKVMrKohAcdvazlSMpKXA=="}
    Payload: {
    "PaymentProduct": ["IDEAL"],
    "CommonPaymentData": {
        "Amount": {
            "Amount": "1.00"
        },
        "RemittanceInformation": "iDEAL Standard Flow Minimum fields",
        "RemittanceInformationStructured": {
            "Reference": "iDEALStandardFlow"
        }
    }
}

Response (Signature-related fields "Digest" and "Signature" are conditionally present):

ResponseCode: 201
    
Headers: X-Request-ID=d04820e1-d2da-4def-8def-13062b57d3a6, MessageCreateDateTime=2023-12-29T16:38:45.949Z, Digest=SHA-256=kyULomhnKJVz5IfrMDOWTs5ZpmBTKwjFrF6HO/LQG6s=, Signature=keyId="3EBEF6033C00730D9C6DA05165A3CAA1F31036FB",algorithm="rsa-sha256",headers="messagecreatedatetime x-request-id digest",signature="m//b5oj7D4Vuw5leONeJnlV6P2YvQEPs/fNq9WxE+HsS68iEICh3uMPPwhqv5JLh5UMDudZG0fY/YtvYx3GMUr5DqGaTxplUWW5+l8dV6JM94POvgOveJOPayCMAW0pWd55sbt/IvBJmc19+z6UKMJ5liNwrvYboxYQp3gb9iCeVyqkUPjjDZmo3EvQXV/6gcZAJCNwPy7vAKmGqiI57f/8EJQEZnwopTVMgn77JdpKht/dMw1oulCot4xaxmgcCwwWVxS951yqsNLxKhOnga4zHCe6anjr1F0qL0qZr85z1eDwVfwwAOiv7tGEzGaXszZnOAnsmwMNjktaVvFBPUQ==", Date=Fri, 29 Dec 2023 16:38:45 GMT, Content-Type=application/json;charset=UTF-8}
    Payload: {
    "CommonPaymentData": {
        "ExpiryDateTimestamp": "2023-12-29T20:38:45.925Z",
        "PaymentStatus": "Open",
        "PaymentId": "142641",
        "AspspPaymentId": "0001143558019460"
    },
    "Links": {
        "RedirectUrl": {
            "Href": "https://worldline.com"
        },
        "GetPaymentStatus": {
            "Href": "https://digitalroutingservice.awltest.de/xs2a/routingservice/services/ob/pis/v3/payments/142641/status"
        }
    },
    "UseWaitingScreen": false
}

Example: iDEAL Payment with Fast Checkout

Request (Signature-related fields "Digest" and "Signature" are conditionally mandatory):

    Address: https://digitalroutingservice.awltest.de/xs2a/routingservice/services/ob/pis/v3/payments
    HttpMethod: POST
    Headers: {Accept=application/json, Digest=SHA-256=OCbJurWSWF7ltmMlP/kM4oT9C2p5ZEjh4Oh0hcGrzek=, X-Request-ID=8221d7a3-f41b-514f-bbc8-c39a744d145d, Authorization=Bearer 175a6d1c801969021f1071168661d617a17e3f8ba3824b7401491968644d2704, MessageCreateDateTime=2024-02-14T17:33:58.301Z, Signature=keyId="39d8e82bb33e7e2a09cbcb3ef3eab351ee1c5e8f",algorithm="SHA256withRSA",headers="x-request-id (request-target) digest messagecreatedatetime",signature="CAK3vtjrbVlYjtoi5nmor+hGvOTMHGRT4p+hXHU8MnLv5mJvtQRmQVbzujHENclCxTIyQjo01wy/ckBuYdFj1hyJfWW/JPJ0h1qCZX8/XBrI+IA89ZDqNvcd62wUHOcYeFMtIhcySk03Ln7YRjObIJ1g/ky/jB4/aA0UStAWOstc72YU8S2A+5JLy+lN7MzQoV2KNo3QzOyOzPZ9Ga6/2xdMnq7bG+uSBP9n07JljQPoqPr6onsX7UFSjYtind0kX+6wfH2XjQI2pFEhF1q8brL3ponnmQ053JJpp+dX68HFIuDSXn+O9CHL7HLY51xQIbDilPaocA1dPlPLeSsU+Q==", content-type=application/json; charset=UTF-8}
    Payload: {
    "PaymentProduct": ["IDEAL"],
    "CommonPaymentData": {
        "Amount": {
            "Type": "Fixed",
            "Amount": "24.50",
            "AmountBreakdown": {
                "OrderAmount": "20.50",
                "ShippingCost": "4.00"
            }
        },
        "RemittanceInformation": "iDEAL2.0 FastCheckout Flow",
        "RemittanceInformationStructured": {
            "Reference": "iDEALpurchase21"
        }
    },
    "IDEALPayments": {
        "FlowType": "FastCheckout",
        "ExpectedCheckoutData": {
            "DebtorContactDetails": {
                "FirstName": true,
                "LastName": true,
                "PhoneNumber": true,
                "Email": true
            },
            "ShippingAddress": true,
            "BillingAddress": true
        }
    }
}

Response (Signature-related fields "Digest" and "Signature" are conditionally present):

    ResponseCode: 201
    Headers: {X-Request-ID=e3727e35-e3fd-4bb9-9c6c-1725da231527, MessageCreateDateTime=2024-02-14T17:33:58.939Z, Digest=SHA-256=16eS+f5lOwGtN05ukpGcKvDrKt2DR5QCNNsDQfLBe5c=, Signature=keyId="3EBEF6033C00730D9C6DA05165A3CAA1F31036FB",algorithm="rsa-sha256",headers="messagecreatedatetime x-request-id digest",signature="RcDMNd5jy/HiJ9s2QxmzwfKuXMTzT4Pk5lp8z0NhOG9fS1VrPVsEcq0u8Hm3C+6UwdPjGDekSC1kytvOm/gHSoZQTIEvpbh99w7yeBCzQNbIQNWr9Fnl4QyXgyrUfVgR889yEGntw+0esl0vu+LpFqi+0CI4rdu5vbzaqLz/oG00D9NC8W0PfEmj469XBevp3hDcnb6ieINmOVo4ZYu2ByaD3p6TC1vN+YYRqw6t/n+qZVjYG3DIhceTtiqsPvoucU7wYVRplqta7GyAK9RGevXzZfY6guiZrsDHl6mWhToKiQoS2YjGE6COF89oOeCfC5NXy4n+/fwKAhqmWBdPsQ==", Date=Wed, 14 Feb 2024 17:33:58 GMT, Content-Type=application/json;charset=UTF-8}
    Payload: {
    "CommonPaymentData": {
        "ExpiryDateTimestamp": "2024-02-14T21:33:58.919Z",
        "PaymentStatus": "Open",
        "PaymentId": "174142",
        "AspspPaymentId": "0001077680035886"
    },
    "Links": {
        "RedirectUrl": {
            "Href": "https://worldline.com"
        },
        "GetPaymentStatus": {
            "Href": "https://routingservice.awltest.de/xs2a/routingservice/services/ob/pis/v3/payments/174142/status"
        }
    },
    "UseWaitingScreen": false
}

GET Payment Status

Endpoint: GET /payments/{paymentId}/status

This endpoint is used to retrieve the status of a payment.

Data model

Legend

Orange fields: mandatory for an iDEAL payment
Purple fields: conditionally mandatory for an iDEAL payment

Request

Response (click to enlarge)

Example: iDEAL payment status

Request (Signature-related fields "Digest" and "Signature" are conditionally mandatory):

Address: https://digitalroutingservice.awltest.de/xs2a/routingservice/services/ob/pis/v3/payments/143374/status
HttpMethod: GET
Headers: {Accept=application/json, Digest=SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=, X-Request-ID=aa9ec3e7-dc34-f625-2e97-e16644ea1e77, Authorization=Bearer 59519322f1f56db6bd1d23ac0e22cf5015088f085970fb9b461ff2684bc2e96a, MessageCreateDateTime=2024-01-08T12:55:34.630Z, Signature=keyId="39d8e82bb33e7e2a09cbcb3ef3eab351ee1c5e8f",algorithm="SHA256withRSA",headers="x-request-id (request-target) digest messagecreatedatetime",signature="W/6ViHZJ/x0/KM61H7mwCZQp2/3WPax5seqLpCby0BXwgpVoFrSmCu5oHF2pLS2AdHuTiE6qFsBnMkfeGMEDwtqCdY0GZVQGwZ6j9+6zjJHwm21xZ+BmXXH4puRgqxt7DSnOou3SkstzCblf4gSL8MqIyYu7n+eLQlWvjl57t7dNgX0sNTwJE/1GgU/ukDyUoJl4aO1n9ID8EnLDUpXunbZ+1pyCPGbfz5/pDMrJsKZ9l58tLxj7IneU+Mnai8UJEqrQ441ONgYCHF7KoDxu15XA+IY7DnwkA5u/+QN7IY5KpHG3zP19m7jiOimkI6lrqLAc2Ld4iehjNMGve7Ci7w=="}

Response (Signature-related fields "Digest" and "Signature" are conditionally present):

    ResponseCode: 200
     
    Headers: {X-Request-ID=3a3df5d3-fa9e-4fee-b9fd-067c23dc91fa, MessageCreateDateTime=2024-01-08T12:55:35.032Z, Digest=SHA-256=pV9HQh/XGpLmawhfj9d/hxYucKkOQCKV9BJ978PeW5k=, Signature=keyId="3EBEF6033C00730D9C6DA05165A3CAA1F31036FB",algorithm="rsa-sha256",headers="messagecreatedatetime x-request-id digest",signature="DMvxRTvhRG1kFAy0JPbBzdoRrXq5C9OUJHl6GMQkdNriG4SeuHGaFpdaDA6NgFw2+Ky/RBYiruL18ul+1ZvmdhlyhMaRqR0J7Jg/m9JMyu3wFunBVINysQ+2yj0ucXRMck/CoBW1mYwjDCGCN7xOofw2mZLV6PHjP9xHaDA855iPYE7HUaukB/qveA/S6B2qsjFxDs5AJh6VSWEoknA1+NJZCEX2VC23bnkMgy92qN6bZch5bL3462yFA/0uA75k9XH3O7+Jesl86tBU3kKATNk5n2//vun+Bg4NlSQjU21m6B+nOZT1M+TUkVzG0KWdByf6yFv/x0rp7hifnFZvjA==", Date=Mon, 08 Jan 2024 12:55:35 GMT, Content-Type=application/json;charset=UTF-8}
    Payload: {
    "PaymentProductUsed": "IDEAL",
    "CommonPaymentData": {
        "PaymentStatus": "SettlementCompleted",
        "PaymentId": "143374",
        "AspspPaymentId": "0001092688873027",
        "AspspId": "10002",
        "DebtorInformation": {
            "Name": "Edsger Wybe Dijkstra - Callback",
            "Agent": "ABNANL2AXXX",
            "Account": {
                "SchemeName": "IBAN",
                "Identification": "NL44RABO0123456789"
            }
        }
    }
}

ob-p-ideal-transaction-flow

Read more about ob-p-ideal-transaction-flow

Transaction Flow

for iDEAL 2.0

In this chapter the transaction flows of two iDEAL payment types are described:

Standard iDEAL payment
- Without profile recognition
- With profile recognition (based on debtor token)
Fast Checkout iDEAL payment (based on browser cookie)

Additional requirements for the iDEAL payments are described in the chapter iDEAL requirements

Standard iDEAL Payment

An iDEAL transaction for a simple single payment is the basis of the iDEAL flow. The actual iDEAL transaction flow that the PSU follows, depends on where the iDEAL transaction is started at the Initiating Party (mobile app or browser, desktop browser) and where the payment authorization takes place at the ASPSP (mobile banking app, desktop browser, mobile browser). Next to this, it also depends on whether a PSU is already registered for iDEAL, and whether a registered PSU is recognized by the iDEAL Hub via a Debtor Token.

The full iDEAL transaction flow broadly follows the following steps:

Shopping Process: The PSU places an order at an Initiating Party and chooses iDEAL as payment method. If the Initiating Party makes use of Debtor Tokens, the Initiating Party shows the preferred ASPSP and IBAN of the recognized PSU alongside the iDEAL payment button.
Transaction Initiation: A transaction is created at the Open Banking Service using the Post /payments API, which responds with a redirect URL to the iDEAL payment page or the ASPSP directly.
Customer Recognition / ASPSP Selection: The PSU is redirected by the Initiating Party (or CPSP) to the iDEAL payment page, where he can choose an ASPSP or scan a QR code (depending on the web/app context). Alternatively, a recognized PSU (by means of browser cookie or debtor token) may be redirected directly to his preferred ASPSP or receive a push notification from his preferred ASPSP to authorize the iDEAL transaction (decoupled flow).
ASPSP Authorization: The PSU is presented with the transaction details at the ASPSP, where he authorizes the iDEAL transaction.
Transaction Confirmation & Return to Initiating Party: When the PSU authorizes the payment, a confirmation is sent by the ASPSP to the iDEAL Hub. If applicable, the PSU may be asked to register a profile with iDEAL. The iDEAL Hub informs the Open Banking Service of the payment status, who in turn informs the Initiating Party. In case the Initiating Party implemented the Post status API, they are informed of the payment status directly by the Open Banking Service. In case of a redirect flow, the PSU is ultimately redirected back to the Initiating Party.

Below are two example screen flows. The top one is using a mobile device throughout. The bottom one starts on a non-mobile device and switches to a mobile device for the ASPSP Authorization.

Figure 1 iDEAL transaction flow example on mobile

Figure 2 iDEAL transaction flow starts on non-mobile device (example)

For the initiation of an iDEAL payment two authentication flows are applicable; described in the table below.

Secure Customer Authentication (SCA) Approach	Indicator in the Post /payments response	Description
Redirect	RedirectUrl	In the Redirect Approach the browser session of the PSU is redirected from the Initiating Party to the iDEAL Hub. The iDEAL Hub will ask the PSU which ASPSP he would like to use (this preference can be stored). The browser session is then redirected to the chosen ASPSP. The ASPSP provides all the pages required for authentication of the PSU and will then ask for authorization of the payment. After that the PSU is redirected back to the Initiating Party.
Decoupled	UseWaitingScreen = true AND RedirectUrl	The decoupled flow can only occur if the 'HttpHeaderUserAgent' , 'PsuId' and 'UseDebtorToken = true' fields are provided in the Post /payments request. The Aspsp could then decide to use the decoupled flow, in that case the Post /payments response will have 'UseWaitingScreen = true' field. UseWaitingScreen is a boolean which is returned in the Post /payments response. If set to true it means the Initiating Party should display a waiting screen while the Aspsp is starting a decoupled flow with the PSU. The RedirectUrl is provided as backup. Currence set the following requirements for the waiting screen: There is a <Back> button, which leads the PSU back to the previous page of the Initiating Party; The Initiating Party MUST make a call to retrieve the status of iDEAL payment; When there is no final status available, the Initiating Party MUST inform the PSU that the payment is not finalised; When a final status is available, the Initiating Party MUST inform the PSU about that status (payment successful, payment failed, etc.) and follow up with the applicable action; There is a <Didn’t receive notification> button, which leads the PSU to the iDEAL Payment Page RedirectUrl to finalise the payment; A message is displayed which informs the PSU about the action that is required, for example: ‘Tap the notification on your phone to pay with the following bank’; The ASPSP name and logo are displayed; This page can be in the look and feel of the Initiating Party.

Secure Customer Authentication (SCA) Approach

Indicator in the Post /payments response

Description

Redirect

RedirectUrl

In the Redirect Approach the browser session of the PSU is redirected from the Initiating Party to the iDEAL Hub. The iDEAL Hub will ask the PSU which ASPSP he would like to use (this preference can be stored). The browser session is then redirected to the chosen ASPSP. The ASPSP provides all the pages required for authentication of the PSU and will then ask for authorization of the payment. After that the PSU is redirected back to the Initiating Party.

Decoupled

UseWaitingScreen = true

AND

RedirectUrl

The decoupled flow can only occur if the 'HttpHeaderUserAgent' , 'PsuId' and 'UseDebtorToken = true' fields are provided in the Post /payments request. The Aspsp could then decide to use the decoupled flow, in that case the Post /payments response will have 'UseWaitingScreen = true' field.

UseWaitingScreen is a boolean which is returned in the Post /payments response. If set to true it means the Initiating Party should display a waiting screen while the Aspsp is starting a decoupled flow with the PSU. The RedirectUrl is provided as backup. Currence set the following requirements for the waiting screen:

There is a <Back> button, which leads the PSU back to the previous page of the Initiating Party;
- The Initiating Party MUST make a call to retrieve the status of iDEAL payment;
  - When there is no final status available, the Initiating Party MUST inform the PSU that the payment is not finalised;
  - When a final status is available, the Initiating Party MUST inform the PSU about that status (payment successful, payment failed, etc.) and follow up with the applicable action;
There is a <Didn’t receive notification> button, which leads the PSU to the iDEAL Payment Page RedirectUrl to finalise the payment;
A message is displayed which informs the PSU about the action that is required, for example: ‘Tap the notification on your phone to pay with the following bank’;
- The ASPSP name and logo are displayed;

This page can be in the look and feel of the Initiating Party.

Sequence diagrams

The sequence diagrams in this paragraph are examples of possible flows for standard iDEAL payments with and without profile recognition, they do not encompass all the possible flows.

In the diagrams below the sequence of requests is shown. The vertical green bars indicate which party is responsible for the session of the PSU. If a party has the session a screen can be displayed. Notice that in the iDEAL 2.0 flow the Initiating Party can receive a notification when the authorisation of the payment is finished on the ASPSP side. In order to receive this notification, the Initiating Party should implement the Post status API, so this can be called by the Open Banking Service. The initiating party also has the option to request the status by calling the Get /payments/status API of the Open Banking Service.

Redirect and no Debtor token

This is an example of an iDEAL payment where the PSU is not recognized by the iDEAL Hub.

Redirect with newly generated Debtor token

The iDEAL payment product has the option to store information about the PSU, such as the favorite bank and the IBAN. In order to use this functionality, the Initiating Party should set the field 'UseDebtorToken = true' in a Post /payments request towards the Open Banking Service. If a new debtor token is generated by the iDEAL Hub the Open Banking Service will return, next to the Status of the payment in Post /status, a PsuID in Post /debtorToken. This PsuID can then be used in subsequent iDEAL payments request for the same PSU (again with 'UseDebtorToken' set to true).

Redirect with existing Debtor token

The Open Banking Service also offers a separate API which can be used to retrieve the preferences of the PSU, the Get /preferences API.

In the sequence diagram below the Get /preferences api is the optional step in the beginning. This flow is using the Debtor Token to reduce the number of steps for the PSU to complete the payment (no ASPSP selection required in the iDEAL Hub).

Decoupled with existing Debtor token

This sequence diagram shows a possible decoupled flow, but is otherwise the same as the 'Redirect with existing debtor token' flow.

In a decoupled flow another device is used to authenticate and authorize the payment, this can be seen in the sequence diagram below by the fact that 2 sessions (green vertical bars) are active at the same time. The PSU doesn't leave the session with the Initiating Party, in the meantime a session is started on another device (for example a smartphone) which handles the interaction between the PSU and the ASPSP. The decoupled flow can potentially speed up the authentication process when bio-metrics are used in the ASPSP's app on the smartphone.

If the following fields are provided in the Post /payments request a decoupled flow can be initiated by the ASPSP:

HttpHeaderUserAgent
PsuId
UseDebtorToken = true

In case of a decoupled flow the Post /payments response will have 'UseWaitingScreen = true' field.

Fast Checkout iDEAL Payment

An iDEAL payment with iDEAL Checkout allows a PSU to centrally manage his shipping, invoice and contact details in its iDEAL profile and provide these to an Initiating Party as part of the iDEAL payment.

In an iDEAL payment with iDEAL Checkout, a PSU is redirected to the iDEAL Payment Page. If the PSU is recognized by a cookie and an iDEAL profile is detected, the shipping address preferences are shown to him on the iDEAL payment page. The PSU then confirms its preferred contact details and shipping address on the iDEAL payment page, after which he proceeds with the transaction through either a redirect to the ASPSP, a QR code scan, or a push notification to its mobile banking app. After the PSU has authorized the payment at the ASPSP, he is redirected back to the Initiating Party. Upon authorization, the Initiating Party receives confirmation of the payment (similar to a regular iDEAL transaction), which will additionally include the chosen contact details and shipping address of the PSU.

Currently only Dutch shipping addresses are allowed for PSUs

Below an example screen flow of a Fast Checkout iDEAL Payment.

Initiating an iDEAL Checkout transaction with the Open Banking v3 API

An iDEAL Checkout transaction can be initiated by indicating this in the FlowType field of the Post /payments. A breakdown of the transaction amount needs to be added to this call, which will be shown to the PSU during the iDEAL Checkout transaction flow alongside its shipping details.

Initiating an iDEAL Checkout transaction

To mark a transaction as iDEAL Checkout, the field FlowType MUST be set to FastCheckout
To initiate an iDEAL Checkout transaction, the AmountBreakdown group MUST be included in the POST /payments call.
- This group MUST include both an OrderAmount and a ShippingCost. If no shipping costs apply, the field must be filled with 0.
The sum of the OrderAmount and ShippingCost MUST be equal to the Amount field, which represents the total transaction amount to be payed by the PSU.
To specify the desired iDEAL Checkout data to be received, the ExpectedCheckoutData group can be set. Only those data fields that are set to true will be included in the callback.

In a iDEAL Checkout transaction, the response of the Post /payments call will always include a URL to the payment page in the Links.RedirectUrl field.

Shipping amount and shipping/invoice address restrictions

When initiating an iDEAL Checkout transaction, the Initiating Party MUST specify the desired iDEAL Checkout data to be received, which can be included in the payment initiation via the ExpectedCheckoutData group
- The Initiating Party MUST comply with the General Data Protection Regulation (GDPR). The Initiating Party SHOULD only request the personal data which is needed to fullfill the agreement with the PSU;
The Initiating Party MUST provide both an OrderAmount and ShippingCost.
The PSU can only add Shipping and Invoice addresses in The Netherlands. Any other non-NL addresses are currently not allowed. Initiating Party's therefore can trust to receive only NL addresses.
It is (currently) not possible to dynamically define or alter the shipping amount based on the PSU’s chosen shipping address. The shipping amount can only be provided one time in the transaction initiation. The shipping amount can also be 0.
In case the PSU cannot or does not want to provide its iDEAL Checkout data, the transaction is canceled. This means that if an iDEAL Checkout transaction is initiated, a successful and payed transaction will always include the iDEAL Checkout data.

Selection/registration of iDEAL Checkout data by PSU

After initiating an iDEAL Checkout, the PSU is redirected to the iDEAL Payment Page. Here, the amount breakdown in order amount and shipping amount is shown, next to the regular payment details.

If the PSU is recognized by a browser cookie, the known shipping address preferences from its iDEAL profile are shown, in addition to the regular profile preferences. Note that only the data fields indicated in ExpectedCheckoutData will be shown to the PSU (this applies to all iDEAL Checkout flows).
Profile information presented will be partly masked and can only be fully shown if the PSU authenticates via its ASPSP.
If a registered PSU does not have any shipping address registered with its profile yet, it will first be asked to provide an address before continuing with the iDEAL Checkout transaction.
If the PSU is not recognized, it will first be asked whether the PSU has a registered iDEAL profile. In case of an existing profile, the PSU will be asked to select its ASPSP and is redirected to that ASPSP for authentication. After successful authentication, the PSU will return to the iDEAL payment page to view its (unmasked) profile and iDEAL Checkout data.
At any time during the iDEAL Checkout flow, the PSU may choose to change its preferred address for the transaction or add a new address. This is done on the iDEAL payment page.
If the PSU is not recognized and is a new PSU, the PSU is asked to register an iDEAL profile, including data for iDEAL Checkout.

Shipping data in transaction callback

After confirming the selected delivery details and preferred IBAN, the PSU is redirected to the ASPSP for authenticating and authorizing the payment. This is done at the ASPSP, similar to a regular transaction.

If the PSU was not registered with iDEAL yet, a registration flow was initiated at the iDEAL payment page.

After the PSU has confirmed the transaction payment at the ASPSP, the PSU’s iDEAL Checkout data (like shipping address) is added to the Post /status callback alongside the other payment details. The iDEAL Checkout data can be found in the DebtorInformation group. Note that only data fields that were indicated in the ExpectedCheckoutData will be included in the callback.

Sequence diagram

This iDEAL Fast Checkout flow is based on de the recognition of the PSU by the iDEAL 2.0 Hub based on a browser cookie. In the sequence diagram below the PSU is recognized. This flow will simplify the checkout screen of the Initiating Party; shipping, invoice and contact details are all handled by the iDEAL Hub. The shipping data is provided in the Post /status request or the Get /payments/status response after the payment was finalized at the ASPSP.

Subscribe to

Bank Selection Interface

General Features

Remind current PIN of the card

Retrieve Card

Search card with PAN, PAN sequence number and expiry date

Retrieve Card Contract for a Card

Retrieve Card event list

Retrieve blocking information for a card

Update blocking information for a card

Update blocking information for all cards with same PAN or same PAN reference

Create emergency card

Create new TAN

Retrieve CVV

Display Pin for a card

Set a Pin for a card

Reorder new Pin for a card

List orders for a card

Retrieve card order for a card

Reset Pin try counter for a card

Advice a product extension for a card

Get parameters for a letter template

List of available letter templates for cards

Retrieve a specific letter template

Retrieve letter for a card

Generate a letter for a card

Validate a letter for a card

Delete a letter for a card

Release orders for a card

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

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

Merchant payments

GET Merchant payments calls

Card Lifecycle Management

Activate a card

Block a card

Unblock a card

Block all cards with same PAN or same PAN reference

Unblock all cards with same PAN or same PAN reference

Deactivate a card

Replace a card

Block and replace a card

General Contract Management

Create A Consumer Contract

Search Contracts By criteria​

Retrieve Contract

Update Addresses Of All Contract Members

Add Card To An Existing Contract

Update Contract

List Accounts For A Contract

List Card Contracts For A Contract

Suspend A Contract

Cancel A Contract Suspension

Close Contract

Cancel A Contract Closing

List Contract Fees For A Contract

Update Contract Fees For A Given Contract And Card Account

Retrieve Contract Owner A Contract

Switch Between Principal And Supplementary Cards

List Legitimacy Documents For A Contract

Update Legitimacy Document Of A Contract Customer

Sign A Contract

Replace A Customer Within A Consumer Contract

Refund fee on demand

Search Contracts By criteria​ (multi-issuers)

Subscribe to add-on

Unsubscribe to add-on

Retrieve the list of add-on services

Advice a product extension

Debtor preference retrieval API

Get Preferences

Data model

Example

Payment Initiation API

Payment Status

POST Payments

Data model

Example: Standard iDEAL payment without Debtor token

Example: iDEAL Payment with Fast Checkout

GET Payment Status

Data model

Search Contracts By criteria

Search Contracts By criteria (multi-issuers)