The Push Notification APIs described in this chapter need to be implemented on the Initiating Party side, if the Initiating Party decides to use them. The Open Banking Service will post notifications to these endpoints.

POST Status

Endpoint: POST /status

Base URL: URL provided by you as part of your onboarding

This API will notify the initiating party about the status of the payment. More details about the fields can be found in the API reference.

Data model

Request (Click to enlarge)	Response

IT Security Management refers to the systematic approach of identifying, assessing, and mitigating risks to protect institution's resources and information from unauthorized access, damage, disruption or misuse. The implementation of control mechanisms such as policies and procedures are natural to ensure the confidentiality and availability of critical business information and infrastructure.

IT Security Management covers a wide range of aspects such as cybersecurity, cryptography, data protection, risk management, incident response and of course compliance with all applicable standards. 

We effectively manage security and minimize the impact of security breaches:

As a trusted partner of the largest financial institutions around the world, we maintain a secure and trusted environment for your operations -  Authentication, Authorization and Message Integrity of requests between you and Worldline are guaranteed through three different mechanisms:

Transport Level Security   -   Digital Signatures   -   Access Tokens

Transport Level Security

On the transport level all requests to the Open Banking Service, as well as all requests sent by the Open Banking Service MUST be encrypted using TLS and be made over HTTPS. TLS 1.3 SHOULD be used; TLS 1.2 MAY be used. Anything below TLS 1.2 MUST NOT be used and will be refused by the Open Banking Service. The TLS authentication method used is one-way, that means in requests to Worldline your server authenticates itself with its certificate and in case of requests from Worldline to you, the latter authenticates itself with its certificate.

Any connection without TLS encryption, such as plain http will be refused.

Digital Signatures

Signing the authorization request

On the application level, your application is authenticated and authorized by sending a digitally signed request to the Authorization API endpoint (see Authorization API). The signature validation allows to check the authenticity and integrity of the request. This is achieved by applying the "Authorization" scheme as described in Datatracker and further detailed in Authorization API.

In order to generate the string that is signed with a key, you should use the values of each HTTP header field in the `headers` Signature Parameter, in the order they appear in the `headers` Signature Parameter.

The `headers` Signature Parameter is fixed: headers=”app client id date”.

The header field string is created by concatenating the lowercased header field name followed with an ASCII colon `:`, an ASCII space ` `, and the header field value. Leading and trailing optional whitespace (OWS) in the header field value MUST be omitted. If the value is not the last value, then an ASCII newline `\n` is appended.

Example: For the request:

POST /authorize/token HTTP/1.1
App: IDEAL
Date: Fri, 25 Mar 2022 20:51:35 GMT
Client: idealClient
Id: 434

The concatenated String to sign would be:

app: IDEAL
client: idealClient
id: 434
date: Fri, 25 Mar 2022 20:51:35 GMT

The signature algorithm is fixed: algorithm=”SHA256withRSA”.

The ‘keyId’ Signature Parameter is the thumbprint of the used certificate, viewed with the SHA1 algorithm. The private key associated with `keyId` is used to generate a digital signature on the concatenated signature string applying the SHA256withRSA algorithm. The complete Authorization header looks then like this:

Authorization: Signature keyId=”DCAC7209573D506FC56095B8B23E8555A8F38B29”, algorithm=”SHA256withRSA”, headers=”app client id date”, signature=” guoLSHgl/zGRujqkDnmaWCL8kgCVnDazqkKu7nWU/uAHrS+M9eQsI8ueB4uWgxyPOnZps3vpNgkW1f4aBsdFYLS0jYeup4yhCMN6vis2zfMKxUhZFkjELslQkit9Gwc9pqvcyH0IxUnDLbCQwkiYjf6nGbP1YNfoxVXQpfq6i6CbIXCotLfwH2kbkrnSWwAS5skZY77+znmLDjtP3et2K94C36yPo0EEGqGkQ5xkD7owA7YxzA30xzsvkDvU3hzDzTK5wZmsgVsoyjRvMrokG0HrszUpNTwUtxflukcgs0pH7GuT+JrIpQ55f1dpzULqxeBggnCvD9DRSuKeTakqlw==”

You should provide the used public certificate to our Support team or upload it in the back-office so that the Open Banking Service is able to validate the signature. If the signature could be validated and the sender has a valid subscription, a response containing an access token is returned. This access token can be used in all follow-up requests until it is expired. After expiration a new access token must be requested from the Authorization API endpoint.

Signing requests and responses

Signing requests and responses could be enforced depending on  your preferred configuration. The following options exist:

• Requests to the Payment Initiation, Payment Status and Debtor Preference APIs sent to Worldline

• Requests to the Notification API, sent by Worldline to you

• Responses sent back from Worldline to you

The digital signing is done by applying the “Signature” scheme as described in Signatures. This is equivalent to the “Authorization” scheme and the same procedure is followed to generate the signature and header parts but it uses the Signature header instead of the Authorization header.

A notification request or response from Open Banking Service to the Initiating Party may contain for example a header like:

Signature: keyId="2DOXXL7lNBNKJSMHKO2IBQC1", algorithm="SHA256withRSA", headers="digest x-request-id messagecreatedatetime", signature="lulVhOhRwFs5G8+uGCh3BjJHBG540AyTCyaKhr9QE71YTtljxFt1b7i55C9QROw/zGt+iac3cBfGGRiTAfW4ta9Hn8+u7LvyfYHFcdxBhNj7T6dgrv+MLG6aI6hw/3Cwmkz/OwESBrQJzISWf8/0bgYNuXnuPf5r7BGMhHdhIr+RNxocW6wkSOEVQfOGYazy7YsoJhVEwNEt9gN++sw9HVfaxmwjl8MqxGNcLoVAgoGMcUOvNhjATA1MSzOj2cmw6kdi2yY2w7XiMuU9Tma0jQ3CGKhxIkD8Na2Vq1K2bs/n2DOxxL7lNbnKjsmhkO2ibQc1+RV3pXQJ1SDSI3EW/w=="

The Initiating Party may then validate that the content of the sent message is correct and has not been altered during transmission or storage. For this please use Worldline public certificate that can be provided to you by our Support team or downloaded from the back-office.

Access Token

API calls towards Worldline

The access token as has been returned from the Authorization request endpoint can be used for subsequent requests towards Worldline. The default validity time of the access token is one hour after which a new one must be requested from the Authorization endpoint. A refresh token does not exist for this type of request.

The access token must be put into the request Authorization header like for example: Authorization:Bearer 4944daeae6c9115a10dafecbfad4a9c

With the access token the Open Banking Service can validate and authorize the request.

API calls from Worldline (for Notifications)

The access token used in requests from the Open Banking Service towards you can be configured in the Back-office, on the subscription page (the name of the field is: 'Notification BearerToken'). The token is static and does not have validity time.

The access token will be placed in the notification request Authorization header. With the access token you can validate and authorize the request.

Structure

We support 3 hierarchy levels of entities using Worldline Open Banking Platform:

1. Tenant - the highest level of hierarchy: 

A Tenant is typically licensed as AISP or PISP:

The AISP Tenant is authorized to retrieve account information from financial institutions - with the consent of the customer (see 2. Initiating Party or Merchant). This  can be a bank or a payment institution, that offers Services according to  PSD2.

The PISP Tenant is is authorized to initiate payments into or out of an consumer’s bank account - on behalf of a customer (see 2. Initiating Party or Merchant). PISPs are allowed to withdraw money directly from the customer's account, as long as the customer has given his consent. 

2. Initiating Party / Merchant

- client of AISP and / or PISP

The Initiating Party is the client of a licensed AISP /PISP (see 1. Tenant) who wants to access data or initiate payments on behalf of his customers. Typically this is the role, you will have in this hierarchy. 

(The Initiating Party can also be setup in the role of a Third Party Provider (TPP) as an intermediate between Merchants and ASPSPs / PISPs - the TPP  and provides an interface used by the Merchant.

3. Sub Merchant

- a client of the Initiating Party

The hierarchy is used in order to setup appropriate access rights (e.g. specific geographies or sub services) and for reporting purposes.

Setup

Tenant setup is done by Worldline, while the Merchant and Sub Merchant setup can be managed by yourself via: 

• Back Office; a set of screens which can be offered white labeled

• Merchant Subscription Management API; useful if integration with an existing CRM system is desired.

You already would like to kick off your onboarding or you might have further questions?
Please contact us to get access to the Back Office and kick off your onboarding.

Tenant Setup

Worldline sets up the Tenant on base of his requirements. Here are the main topics, which are configurable by the tenant and set up by Worldline:

- Which services are available (e.g. PIS, AIS, Ideal etc.)?
- Which User Roles should be set up? 
- Which modules should be ready for use in the Back office and for which roles should the modules be available?
- Should Merchant Self-Onboarding be available?
- Which Way of Integration should be set up?
- Should API's (for Merchant- and Subscription Management) be available?
- Additional features as Content Style, Translations, GUI Languages, Input Field Configuration etc. 

Here you will find implementation details of our Payment Products. All Payment Products except iDeal / iDeal 2.0  are based on Account-to-Account payments.

Account-to-Account Payments

A payment request can be initiated by a payer or a payee. To be processed by the payer's bank, the payment needs to be authorised by the payer to the bank. A payer's bank will apply a strong customer authentication to ensure payer's identity. This can lead to multiple flows in which a payment can be completed.

We support single SEPA, Instant SEPA, Domestic and cross-border payments with our Payment API. In addition, we can offer also an ability to initiate bulk payments, periodic or scheduled payments. To learn what kind of payments is supported by payer's bank, you should use Reach API once a day.

For faster integration and better user experience we offer a set of predefined screens that could be customised with your branding allowing to choose the payer's bank and handling the complexity of different PSD2 authorization flows (redirect / decoupled / embedded), so that you will be able to focus on your product and leave the boring stuff to us.

You can learn about payment execution progress either by polling the payment status by yourself or by subscribing to our push notifications. If you chose to subscribe to push notifications, we will continuously check with the bank on payment authorisation and execution progress and proactively notify you on the changes.

We also offer a Refund API allowing to refund historical payments.

Once you finished your implementation we recommend to go through the list of suggested testing scenarios.

Creditor Account Options

A merchant on the Worldline Open Banking Platform, can be setup as either a E-Commerce or p2p merchant. When E-Commerce is selected, the Open banking Platform will initialize payments using a predefined creditor account. When p2p is selected the merchant can specify the creditor account in the post payments API call.

For E-Commerce merchants an additional service is available: In case you act as a payee and hold multiple bank accounts, you may want allow Worldline to choose the account that will be credited as a result of the payment. In case you hold bank account with the same bank as the payer, this account will be prioritised to ensure quick intra-bank settlement and reduce transaction fees paid to the bank. If you are interested, please request to switch on the Dynamic Creditor Account Lookup feature for you during the integration phase.

iDEAL Payments

We allow banks to become acquirers for iDeal 2.0 transactions in Netherlands. That means that merchants who are the clients of the bank will be able to initiate iDeal payments using our Payment API.

You can learn about payment execution progress either by polling the payment status by yourself or by subscribing to our push notifications. If you chose to subscribe to push notifications, we will continuously check with the bank on payment authorisation and execution progress and proactively notify you on the changes.

We also offer a Refund API allowing to refund historical payments.

Need help?

Please get in touch with us and we will  help you to integrate our APIs.

Version 2.7.1 to 2.8.0

What's New

GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/turnover-information

Retrieve turnover information for an account

The API is used to get the turnover information for an account

GET /issuers/{issuerId}/accounts/{accountReference}/turnover-information

Retrieve turnover information for an account

The API is used to get the turnover information for an account

GET /issuers/{issuerId}/companies/{customerReference}

Retrieve company's information

PUT /issuers/{issuerId}/companies/{customerReference}

Update company

The "update company" API allows the user to update the attributes of a customer. To identify the customer, it is needed to provide:

• The issuer ID
• The customer reference (internal or external) for which updates are required

The customer reference can be retrieved by using the "list customers" API. All the attributes must be given in input even if they remain unchanged. For that, It can be needed to use the "retrieve customer" API to get all the current attributes.

PATCH /issuers/{issuerId}/companies/{customerReference}

Update company partially

The "update company partially" API allows the user to update the attributes of a customer. To identify the customer, it is needed to provide:

• The issuer ID
• The customer reference (internal or external) for which updates are required

The customer reference can be retrieved by using the "List customers" API. With this API, only attributes that need to be updated must be given in input.

GET /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}

Retrieve company information by external reference

PUT /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}

Update Company

The "update Company" API allows the user to update the attributes of a customer. To identify the customer, it is needed to provide:

• The issuer ID
• The customer reference (internal or external) for which updates are required

The customer reference can be retrieved by using the "list customers" API. All the attributes must be given in input even if they remain unchanged. For that, It can be needed to use the "retrieve customer" API to get all the current attributes.

PATCH /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}

Update Company partially

The "update customer partially" API allows the user to update the attributes of a customer. To identify the customer, it is needed to provide:

• The issuer ID
• The customer reference (internal or external) for which updates are required

The customer reference can be retrieved by using the "List customers" API. With this API, only attributes that need to be updated must be given in input.

GET /issuers/{issuerId}/companies

Retrieve list of company's information

POST /issuers/{issuerId}/companies

Create company

GET /issuers/{issuerId}/companies/{customerReference}/addresses

Retrieve company's Address information list

POST /issuers/{issuerId}/companies/{customerReference}/addresses

Create address for a company customer

The API creates an address for the customer, identified with his reference. An address includes the following information:

• the issuer address external reference
• the label (eg MAIN_POSTAL_ADDRESS),
• the type (mail address, phone number, email) and the corresponding data
• the address usages
• the start date.

For information, the main postal address is mandatory.

In return, the API provides the address Reference calculated by our system.

GET /issuers/{issuerId}/companies/{customerReference}/addresses/{addressReference}

Retrieve company's address information by address ref

PUT /issuers/{issuerId}/companies/{customerReference}/addresses/{addressReference}

Update company address

The API updates all the attributes of a customer's address identified with the reference of the customer and the reference of the address. All the attributes must be provided even those unchanged. The identifiers stay unchanged.

GET /issuers/{issuerId}/companies/{customerReference}/addresses/external-addresses/{issuerAddressExternalReference}

Retrieve company's address information by externalAddress

PUT /issuers/{issuerId}/companies/{customerReference}/addresses/external-addresses/{issuerAddressExternalReference}

Update company address

The API updates all the attributes of a customer's address identified with the reference of the customer and the reference of the address. All the attributes must be provided even those unchanged. The identifiers stay unchanged.

GET /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/addresses

Retrieve company's Address information list by external reference

POST /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/addresses

Create address for a company

The API creates an address for the customer, identified with his reference. An address includes the following information:

• the issuer address external reference
• the label (eg MAIN_POSTAL_ADDRESS),
• the type (mail address, phone number, email) and the corresponding data
• the address usages
• the start date.

For information, the main postal address is mandatory.

In return, the API provides the address Reference calculated by our system.

GET /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/addresses/{addressReference}

Retrieve address information by company external reference and address reference

PUT /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/addresses/{addressReference}

Update company address

The API updates all the attributes of a customer's address identified with the reference of the customer and the reference of the address. All the attributes must be provided even those unchanged. The identifiers stay unchanged.

GET /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/addresses/external-addresses/{issuerAddressExternalReference}

Retrieve address information by company external reference and address external reference

PUT /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/addresses/external-addresses/{issuerAddressExternalReference}

Update company address

The API updates all the attributes of a customer's address identified with the reference of the customer and the reference of the address. All the attributes must be provided even those unchanged. The identifiers stay unchanged.

POST /issuers/{issuerId}/companies/{customerReference}/addresses/{addressReference}/activate

Activate address of a company

POST /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/addresses/{addressReference}/activate

Activate address of a company

POST /issuers/{issuerId}/companies/{customerReference}/addresses/external-addresses/{issuerAddressExternalReference}/activate

Activate address of a company

POST /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/addresses/external-addresses/{issuerAddressExternalReference}/activate

Activate address of a company

POST /issuers/{issuerId}/companies/{customerReference}/addresses/{addressReference}/deactivate

Deactivate address of a company

POST /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/addresses/{addressReference}/deactivate

Deactivate address of a company

POST /issuers/{issuerId}/companies/{customerReference}/addresses/external-addresses/{issuerAddressExternalReference}/deactivate

Deactivate address of a company

POST /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/addresses/external-addresses/{issuerAddressExternalReference}/deactivate

Deactivate address of a company

POST /issuers/{issuerId}/companies/{customerReference}/addresses/{addressReference}/address-usages

Create an address usage for a company

This API allows to link a usage determined by its name (e.g. STATEMENT_SENDING), its entity reference (e.g. card contract reference) and its service code (e.g. ACCOUNT_SERVICE) and the address (identified with its internal reference) of a company (identified with its external reference).

DELETE /issuers/{issuerId}/companies/{customerReference}/addresses/{addressReference}/address-usages

Remove an address usage of a company

The API deletes the address usages linked to one address. These address usages are filtered by the request params : addressUsageName (for definition see the ressource addressUsage), mandatory entityReference (for definition see the ressource addressUsage), optional serviceCode (for definition see the ressource addressUsage), mandatory If the entityReference is empty and the API finds several addresseUsages (for the addressUsageName and serviceCode in request param), then the list of addressUsages will be deleted.

POST /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/addresses/{addressReference}/address-usages

Create an address usage for a company

The address usage describes for which business case the address will be used (e.g., statement sending, card delivery, ...). The complete authorized values list is shared during the product configuration between the issuer and WL. This API allows a usage determined by its name (e.g. STATEMENT_SENDING) to be linked to the entity reference of the address (e.g. card contract reference) and the service code (e.g. ACCOUNT_SERVICE)

DELETE /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/addresses/{addressReference}/address-usages

Remove an address usage of a company

The API deletes the address usages linked to one address. These address usages are filtered by the request params : addressUsageName (for definition see the ressource addressUsage), mandatory entityReference (for definition see the ressource addressUsage), optional serviceCode (for definition see the ressource addressUsage), mandatory If the entityReference is empty and the API finds several addresseUsages (for the addressUsageName and serviceCode in request param), then the list of addressUsages will be deleted.

POST /issuers/{issuerId}/companies/{customerReference}/addresses/external-addresses/{issuerAddressExternalReference}/address-usages

Create an address usage for a company

The address usage describes for which business case the address will be used (e.g., statement sending, card delivery, ...). The complete authorized values list is shared during the product configuration between the issuer and WL. This API allows a usage determined by its name (e.g. STATEMENT_SENDING) to be linked to the entity reference of the address (e.g. card contract reference) and the service code (e.g. ACCOUNT_SERVICE)

DELETE /issuers/{issuerId}/companies/{customerReference}/addresses/external-addresses/{issuerAddressExternalReference}/address-usages

Remove an address usage of a company

The API deletes the address usages linked to one address. These address usages are filtered by the request params : addressUsageName (for definition see the ressource addressUsage), mandatory entityReference (for definition see the ressource addressUsage), optional serviceCode (for definition see the ressource addressUsage), mandatory If the entityReference is empty and the API finds several addresseUsages (for the addressUsageName and serviceCode in request param), then the list of addressUsages will be deleted.

POST /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/addresses/external-addresses/{issuerAddressExternalReference}/address-usages

Create an address usage for a company

This API allows to link a usage determined by its name (e.g. STATEMENT_SENDING), its entity reference (e.g. card contract reference) and its service code (e.g. ACCOUNT_SERVICE) and the address (identified with its external reference) of a company (identified with its external reference).

DELETE /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/addresses/external-addresses/{issuerAddressExternalReference}/address-usages

Remove an address usage of a company

The API deletes the address usages linked to one address. These address usages are filtered by the request params : addressUsageName (for definition see the ressource addressUsage), mandatory entityReference (for definition see the ressource addressUsage), optional serviceCode (for definition see the ressource addressUsage), mandatory If the entityReference is empty and the API finds several addresseUsages (for the addressUsageName and serviceCode in request param), then the list of addressUsages will be deleted.

GET /issuers/{issuerId}/corporate-contracts/{contractReference}/corporate-employee-accounts/{accountReference}

Retrieve corporate employee Accounts

This API allows retrieving a particular corporate employee accounts from its reference or its issuer external reference

PATCH /issuers/{issuerId}/corporate-contracts/{contractReference}/corporate-employee-accounts/{accountReference}

Update Corporate employee account

The API allows to update a corporate Employee account

GET /issuers/{issuerId}/corporate-contracts/{contractReference}/corporate-employee-accounts/external-accounts/{issuerAccountExternalReference}

Retrieve corporate employee Accounts With External Account Ref

This API allows retrieving a particular corporate employee accounts from its reference or its issuer external reference

PATCH /issuers/{issuerId}/corporate-contracts/{contractReference}/corporate-employee-accounts/external-accounts/{issuerAccountExternalReference}

Update Corporate employee account by external account

The API allows to update a corporate Employee account

GET /issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/corporate-employee-accounts/external-accounts/{issuerAccountExternalReference}

Retrieve corporate employee Accounts With External Contract Ref And External Account Ref

This API allows retrieving a particular corporate employee accounts from its reference or its issuer external reference

PATCH /issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/corporate-employee-accounts/external-accounts/{issuerAccountExternalReference}

Update Corporate employee account by external contract and account

The API allows to update a corporate Employee account

GET /issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/corporate-employee-accounts/{accountReference}

Retrieve corporate employee Accounts With External Contract Ref

This API allows retrieving a particular corporate employee accounts from its reference or its issuer external reference

PATCH /issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/corporate-employee-accounts/{accountReference}

Update Corporate employee account By external contract

The API allows to update a corporate Employee account

GET /issuers/{issuerId}/companies/{customerReference}/corporate-contracts

List corporate contracts for a company

The API returns all the corporate contracts where the company belongs to

GET /issuers/{issuerId}/companies/external-customers/{issuerCustomerExternalReference}/corporate-contracts

List corporate contracts for a company

The API returns all the corporate contracts where the company belongs to

GET /issuers/{issuerId}/corporate-contracts/{contractReference}

Retrieve corporate contract

This API allows retrieving a particular corporate 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 if any, such as its current status (scheduled, done, cancelled), 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)), card contracts, cards

POST /issuers/{issuerId}/corporate-contracts/{contractReference}/close

Close Corporate contract

The API allows to close a corporate contract identified by the Contract reference. The contract can be closed immediately or in the future at a date provided by the issuer or at the card expiry date.

As result, For immediate closure : The contract is closed, the cards within the contract are deactivated, the closing 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 closing is triggered for the accounts.

POST /issuers/{issuerId}/corporate-contracts/external-contracts/{issuerContractExternalReference}/close

Close Corporate contract

The API allows to close a Corporate contract identified by the Issuer Contract external reference or the Contract reference. The contract can be closed immediately or in the future at a date provided by the issuer or at the card expiry date.

As result, For immediate closure : The contract is closed, the cards within the contract are deactivated, the closing 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 closing is triggered for the accounts.

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

Declare counterfeit card

What's Changed

POST /issuers/{issuerId}/cards/pin-state

Response:

• Changed property data (object CardStates)
  • Added property expiryDate (string)
  • Added property status (string)
  • Added property blockingReason (string)

POST /issuers/{issuerId}/contracts/{contractReference}/force-product-change

Response:

• Changed property data (object ForceProductChangeResponse)
  • Added property originalContract (object)
  • Added property changedContract (object)
  • Added property productChangeInformation (object)
  • Deleted property oldContract (object)
  • Deleted property newContract (object)

POST /issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/force-product-change

Response:

• Changed property data (object ForceProductChangeResponse)
  • Added property originalContract (object)
  • Added property changedContract (object)
  • Added property productChangeInformation (object)
  • Deleted property oldContract (object)
  • Deleted property newContract (object)

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

Response:

• Changed property data (object Card)
  • Added property logoReference (string)
  • Added property dispatchCode (string)
  • Added property automaticDeactivationDate (string)
  • Deleted property replacementForAutomaticDeactivationDate (string)
  • Changed property cardContract (object CardContract)
    • Changed property cards (array)
      • Changed items (object Card)
        • Added property logoReference (string)
        • Added property dispatchCode (string)
        • Added property automaticDeactivationDate (string)
        • Deleted property replacementForAutomaticDeactivationDate (string)

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

Request body:

• Changed property replaceCardRequest (object ReplaceCardRequest)
  • Added property forceNewPIN (boolean)

Response:

• Changed property data (object BlockAndReplaceCardResponse)
  • Changed property replaceCardResponse (object ReplaceCardResponse)
    • Added property originalContract (object)
    • Added property changedContract (object)
    • Added property productChangeInformation (object)
    • Changed property card (object ReplaceCardResponse.Card)
      • Added property automaticDeactivationDate (string)
      • Deleted property replacementForAutomaticDeactivationDate (string)
    • Changed property newRelatedCardList (array)
      • Changed items (object ReplaceCardResponse)
        • Added property originalContract (object)
        • Added property changedContract (object)
        • Added property productChangeInformation (object)
        • Changed property card (object ReplaceCardResponse.Card)
          • Added property automaticDeactivationDate (string)
          • Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/orders/{orderReference}

Response:

• Changed property data (object Order)
  • Changed property card (object Card)
    • Added property logoReference (string)
    • Added property dispatchCode (string)
    • Added property automaticDeactivationDate (string)
    • Deleted property replacementForAutomaticDeactivationDate (string)
    • Changed property cardContract (object CardContract)
      • Changed property cards (array)
        • Changed items (object Card)
          • Added property logoReference (string)
          • Added property dispatchCode (string)
          • Added property automaticDeactivationDate (string)
          • Deleted property replacementForAutomaticDeactivationDate (string)

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

Request body:

• Added property forceNewPIN (boolean)

Response:

• Changed property data (object ReplaceCardResponse)
  • Added property originalContract (object)
  • Added property changedContract (object)
  • Added property productChangeInformation (object)
  • Changed property card (object ReplaceCardResponse.Card)
    • Added property automaticDeactivationDate (string)
    • Deleted property replacementForAutomaticDeactivationDate (string)
  • Changed property newRelatedCardList (array)
    • Changed items (object ReplaceCardResponse)
      • Added property originalContract (object)
      • Added property changedContract (object)
      • Added property productChangeInformation (object)
      • Changed property card (object ReplaceCardResponse.Card)
        • Added property automaticDeactivationDate (string)
        • Deleted property replacementForAutomaticDeactivationDate (string)

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

Response:

• Changed property data (object Card)
  • Added property logoReference (string)
  • Added property dispatchCode (string)
  • Added property automaticDeactivationDate (string)
  • Deleted property replacementForAutomaticDeactivationDate (string)
  • Changed property cardContract (object CardContract)
    • Changed property cards (array)
      • Changed items (object Card)
        • Added property logoReference (string)
        • Added property dispatchCode (string)
        • Added property automaticDeactivationDate (string)
        • Deleted property replacementForAutomaticDeactivationDate (string)

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

Request body:

• Changed property replaceCardRequest (object ReplaceCardRequest)
  • Added property forceNewPIN (boolean)

Response:

• Changed property data (object BlockAndReplaceCardResponse)
  • Changed property replaceCardResponse (object ReplaceCardResponse)
    • Added property originalContract (object)
    • Added property changedContract (object)
    • Added property productChangeInformation (object)
    • Changed property card (object ReplaceCardResponse.Card)
      • Added property automaticDeactivationDate (string)
      • Deleted property replacementForAutomaticDeactivationDate (string)
    • Changed property newRelatedCardList (array)
      • Changed items (object ReplaceCardResponse)
        • Added property originalContract (object)
        • Added property changedContract (object)
        • Added property productChangeInformation (object)
        • Changed property card (object ReplaceCardResponse.Card)
          • Added property automaticDeactivationDate (string)
          • Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/cards/{cardReference}/orders/{orderReference}

Response:

• Changed property data (object Order)
  • Changed property card (object Card)
    • Added property logoReference (string)
    • Added property dispatchCode (string)
    • Added property automaticDeactivationDate (string)
    • Deleted property replacementForAutomaticDeactivationDate (string)
    • Changed property cardContract (object CardContract)
      • Changed property cards (array)
        • Changed items (object Card)
          • Added property logoReference (string)
          • Added property dispatchCode (string)
          • Added property automaticDeactivationDate (string)
          • Deleted property replacementForAutomaticDeactivationDate (string)

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

Request body:

• Added property forceNewPIN (boolean)

Response:

• Changed property data (object ReplaceCardResponse)
  • Added property originalContract (object)
  • Added property changedContract (object)
  • Added property productChangeInformation (object)
  • Changed property card (object ReplaceCardResponse.Card)
    • Added property automaticDeactivationDate (string)
    • Deleted property replacementForAutomaticDeactivationDate (string)
  • Changed property newRelatedCardList (array)
    • Changed items (object ReplaceCardResponse)
      • Added property originalContract (object)
      • Added property changedContract (object)
      • Added property productChangeInformation (object)
      • Changed property card (object ReplaceCardResponse.Card)
        • Added property automaticDeactivationDate (string)
        • Deleted property replacementForAutomaticDeactivationDate (string)

POST /issuers/{issuerId}/contracts/{contractReference}/change-product

Response:

• Changed property data (object ChangeProductResponse)
  • Added property originalContract (object)
  • Added property changedContract (object)
  • Added property productChangeInformation (object)
  • Deleted property oldContract (object)
  • Deleted property newContract (object)

POST /issuers/{issuerId}/contracts/external-contracts/{issuerContractExternalReference}/change-product

Response:

• Changed property data (object ChangeProductResponse)
  • Added property originalContract (object)
  • Added property changedContract (object)
  • Added property productChangeInformation (object)
  • Deleted property oldContract (object)
  • Deleted property newContract (object)

GET /issuers/{issuerId}/credit-transfers/{endToEndId}

Response:

• Changed property data (object CreditTransfer)
  • Added property cancellationDate (string)

GET /issuers/{issuerId}/direct-debits/{endToEndId}

Response:

• Changed property data (object DirectDebit)
  • Added property cancellationDate (string)

GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}

Response:

• Changed property data (object Account)
  • Added property companyEntityExternalReference (string)
  • Deleted property companyAccountExternalReference (string)

GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/authorizations/{authorizationId}

Response:

• Changed property data (object GetAuthorizationResponse)
  • Changed property velocityLimitChecks (array)
    • Changed items (object VelocityLimitCheck)
      • Deleted property name (string)

GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/credit-transfers

Response:

• Changed property data (array)
  • Changed items (object CreditTransfer)
    • Added property cancellationDate (string)

GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/direct-debits

Response:

• Changed property data (array)
  • Changed items (object DirectDebit)
    • Added property cancellationDate (string)

GET /issuers/{issuerId}/accounts/{accountReference}

Response:

• Changed property data (object Account)
  • Added property companyEntityExternalReference (string)
  • Deleted property companyAccountExternalReference (string)

GET /issuers/{issuerId}/accounts/{accountReference}/authorizations/{authorizationId}

Response:

• Changed property data (object GetAuthorizationResponse)
  • Changed property velocityLimitChecks (array)
    • Changed items (object VelocityLimitCheck)
      • Deleted property name (string)

GET /issuers/{issuerId}/accounts/{accountReference}/credit-transfers

Response:

• Changed property data (array)
  • Changed items (object CreditTransfer)
    • Added property cancellationDate (string)

GET /issuers/{issuerId}/accounts/{accountReference}/direct-debits

Response:

• Changed property data (array)
  • Changed items (object DirectDebit)
    • Added property cancellationDate (string)

GET /issuers/{issuerId}/card-contracts/external-card-contracts/{issuerCardContractExternalReference}

Response:

• Changed property data (object CardContract)
  • Changed property cards (array)
    • Changed items (object Card)
      • Added property logoReference (string)
      • Added property dispatchCode (string)
      • Added property automaticDeactivationDate (string)
      • Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/card-contracts/external-card-contracts/{issuerCardContractExternalReference}/cards

Response:

• Changed property data (array)
  • Changed items (object Card)
    • Added property logoReference (string)
    • Added property dispatchCode (string)
    • Added property automaticDeactivationDate (string)
    • Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/card-contracts/{cardContractReference}

Response:

• Changed property data (object CardContract)
  • Changed property cards (array)
    • Changed items (object Card)
      • Added property logoReference (string)
      • Added property dispatchCode (string)
      • Added property automaticDeactivationDate (string)
      • Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/card-contracts/{cardContractReference}/cards

Response:

• Changed property data (array)
  • Changed items (object Card)
    • Added property logoReference (string)
    • Added property dispatchCode (string)
    • Added property automaticDeactivationDate (string)
    • Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/card-contract

Response:

• Changed property data (object CardContract)
  • Changed property cards (array)
    • Changed items (object Card)
      • Added property logoReference (string)
      • Added property dispatchCode (string)
      • Added property automaticDeactivationDate (string)
      • Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/cards/external-cards/{issuerCardExternalReference}/orders

Response:

• Changed property data (array)
  • Changed items (object Order)
    • Changed property card (object Card)
      • Added property logoReference (string)
      • Added property dispatchCode (string)
      • Added property automaticDeactivationDate (string)
      • Deleted property replacementForAutomaticDeactivationDate (string)
      • Changed property cardContract (object CardContract)
        • Changed property cards (array)
          • Changed items (object Card)
            • Added property logoReference (string)
            • Added property dispatchCode (string)
            • Added property automaticDeactivationDate (string)
            • Deleted property replacementForAutomaticDeactivationDate (string)

POST /issuers/{issuerId}/cards/search

Response:

• Changed property data (array)
  • Changed items (object Card)
    • Added property logoReference (string)
    • Added property dispatchCode (string)
    • Added property automaticDeactivationDate (string)
    • Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/cards/{cardReference}/card-contract

Response:

• Changed property data (object CardContract)
  • Changed property cards (array)
    • Changed items (object Card)
      • Added property logoReference (string)
      • Added property dispatchCode (string)
      • Added property automaticDeactivationDate (string)
      • Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/cards/{cardReference}/orders

Response:

• Changed property data (array)
  • Changed items (object Order)
    • Changed property card (object Card)
      • Added property logoReference (string)
      • Added property dispatchCode (string)
      • Added property automaticDeactivationDate (string)
      • Deleted property replacementForAutomaticDeactivationDate (string)
      • Changed property cardContract (object CardContract)
        • Changed property cards (array)
          • Changed items (object Card)
            • Added property logoReference (string)
            • Added property dispatchCode (string)
            • Added property automaticDeactivationDate (string)
            • Deleted property replacementForAutomaticDeactivationDate (string)

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

Response:

• Changed property data (array)
  • Changed items (object Card)
    • Added property logoReference (string)
    • Added property dispatchCode (string)
    • Added property automaticDeactivationDate (string)
    • Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/authorizations

Response:

• Changed property data (array)
  • Changed items (object Authorization)
    • Changed property velocityLimitChecks (array)
      • Changed items (object VelocityLimitCheck)
        • Deleted property name (string)

GET /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/contract

Response:

• Changed property data (object Contract)
  • Added property contractClosedByProductChange (object)
  • Added property contractCreatedFromProductChange (object)
  • Deleted property productChangeInformation (object)
  • Changed property accounts (array)
    • Changed items (object Account)
      • Added property companyEntityExternalReference (string)
      • Deleted property companyAccountExternalReference (string)
  • Changed property cardContracts (array)
    • Changed items (object CardContract)
      • Changed property cards (array)
        • Changed items (object Card)
          • Added property logoReference (string)
          • Added property dispatchCode (string)
          • Added property automaticDeactivationDate (string)
          • Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/accounts/{accountReference}/authorizations

Response:

• Changed property data (array)
  • Changed items (object Authorization)
    • Changed property velocityLimitChecks (array)
      • Changed items (object VelocityLimitCheck)
        • Deleted property name (string)

GET /issuers/{issuerId}/accounts/{accountReference}/contract

Response:

• Changed property data (object Contract)
  • Added property contractClosedByProductChange (object)
  • Added property contractCreatedFromProductChange (object)
  • Deleted property productChangeInformation (object)
  • Changed property accounts (array)
    • Changed items (object Account)
      • Added property companyEntityExternalReference (string)
      • Deleted property companyAccountExternalReference (string)
  • Changed property cardContracts (array)
    • Changed items (object CardContract)
      • Changed property cards (array)
        • Changed items (object Card)
          • Added property logoReference (string)
          • Added property dispatchCode (string)
          • Added property automaticDeactivationDate (string)
          • Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/card-contracts/external-card-contracts/{issuerCardContractExternalReference}/contract

Response:

• Changed property data (object Contract)
  • Added property contractClosedByProductChange (object)
  • Added property contractCreatedFromProductChange (object)
  • Deleted property productChangeInformation (object)
  • Changed property accounts (array)
    • Changed items (object Account)
      • Added property companyEntityExternalReference (string)
      • Deleted property companyAccountExternalReference (string)
  • Changed property cardContracts (array)
    • Changed items (object CardContract)
      • Changed property cards (array)
        • Changed items (object Card)
          • Added property logoReference (string)
          • Added property dispatchCode (string)
          • Added property automaticDeactivationDate (string)
          • Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/card-contracts/{cardContractReference}/contract

Response:

• Changed property data (object Contract)
  • Added property contractClosedByProductChange (object)
  • Added property contractCreatedFromProductChange (object)
  • Deleted property productChangeInformation (object)
  • Changed property accounts (array)
    • Changed items (object Account)
      • Added property companyEntityExternalReference (string)
      • Deleted property companyAccountExternalReference (string)
  • Changed property cardContracts (array)
    • Changed items (object CardContract)
      • Changed property cards (array)
        • Changed items (object Card)
          • Added property logoReference (string)
          • Added property dispatchCode (string)
          • Added property automaticDeactivationDate (string)
          • Deleted property replacementForAutomaticDeactivationDate (string)

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

Response:

• Changed property data (object SignContractResponse)
  • Changed property contract (object SignContractResponse.Contract)

    • New optional properties:

      • contractOwnerIdentifier
      • creationDate
      • productIdentifier

    • Deleted property creationDate (string)

    • Deleted property signatureDate (string)

    • Deleted property issuerBranchCode (string)

    • Deleted property cardReleaseOrder (string)

    • Deleted property productIdentifier (object)

    • Deleted property contractOwnerIdentifier (object)

    • Changed property accounts (array)

      • Changed items (object SignContractResponse.Account)

        • New optional properties:

          • accountGuarantorIdentifier
          • accountOwnerIdentifier

        • Deleted property accountOwnerIdentifier (object)

        • Deleted property accountGuarantorIdentifier (object)

    • Changed property cardContracts (array)

      • Changed items (object SignContractResponse.CardContract)

        • New required properties:

          • cardContractIdentifier
          • cards
          • status

        • New optional properties:

          • principalSupplementaryCardIndicator
          • relatedAccounts

        • Added property cards (array)

        • Deleted property cardHolderIdentifier (object)

        • Deleted property principalSupplementaryCardIndicator (string)

        • Deleted property card (object)

        • Deleted property relatedAccounts (array)

        • Deleted property externalCobadgedCardNumber (string)

        • Deleted property externalCobadgedSequenceNumber (string)

        • Deleted property externalCobadgedExpiryDate (string)

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

Response:

• Changed property data (object SignContractResponse)
  • Changed property contract (object SignContractResponse.Contract)

    • New optional properties:

      • contractOwnerIdentifier
      • creationDate
      • productIdentifier

    • Deleted property creationDate (string)

    • Deleted property signatureDate (string)

    • Deleted property issuerBranchCode (string)

    • Deleted property cardReleaseOrder (string)

    • Deleted property productIdentifier (object)

    • Deleted property contractOwnerIdentifier (object)

    • Changed property accounts (array)

      • Changed items (object SignContractResponse.Account)

        • New optional properties:

          • accountGuarantorIdentifier
          • accountOwnerIdentifier

        • Deleted property accountOwnerIdentifier (object)

        • Deleted property accountGuarantorIdentifier (object)

    • Changed property cardContracts (array)

      • Changed items (object SignContractResponse.CardContract)

        • New required properties:

          • cardContractIdentifier
          • cards
          • status

        • New optional properties:

          • principalSupplementaryCardIndicator
          • relatedAccounts

        • Added property cards (array)

        • Deleted property cardHolderIdentifier (object)

        • Deleted property principalSupplementaryCardIndicator (string)

        • Deleted property card (object)

        • Deleted property relatedAccounts (array)

        • Deleted property externalCobadgedCardNumber (string)

        • Deleted property externalCobadgedSequenceNumber (string)

        • Deleted property externalCobadgedExpiryDate (string)

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

Response:

• Changed property data (object Contract)
  • Added property contractClosedByProductChange (object)
  • Added property contractCreatedFromProductChange (object)
  • Deleted property productChangeInformation (object)
  • Changed property accounts (array)
    • Changed items (object Account)
      • Added property companyEntityExternalReference (string)
      • Deleted property companyAccountExternalReference (string)
  • Changed property cardContracts (array)
    • Changed items (object CardContract)
      • Changed property cards (array)
        • Changed items (object Card)
          • Added property logoReference (string)
          • Added property dispatchCode (string)
          • Added property automaticDeactivationDate (string)
          • Deleted property replacementForAutomaticDeactivationDate (string)

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

Response:

• Changed property data (array)
  • Changed items (object Account)
    • Added property companyEntityExternalReference (string)
    • Deleted property companyAccountExternalReference (string)

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

Response:

• Changed property data (array)
  • Changed items (object CardContract)
    • Changed property cards (array)
      • Changed items (object Card)
        • Added property logoReference (string)
        • Added property dispatchCode (string)
        • Added property automaticDeactivationDate (string)
        • Deleted property replacementForAutomaticDeactivationDate (string)

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

Response:

• Changed property data (object Contract)
  • Added property contractClosedByProductChange (object)
  • Added property contractCreatedFromProductChange (object)
  • Deleted property productChangeInformation (object)
  • Changed property accounts (array)
    • Changed items (object Account)
      • Added property companyEntityExternalReference (string)
      • Deleted property companyAccountExternalReference (string)
  • Changed property cardContracts (array)
    • Changed items (object CardContract)
      • Changed property cards (array)
        • Changed items (object Card)
          • Added property logoReference (string)
          • Added property dispatchCode (string)
          • Added property automaticDeactivationDate (string)
          • Deleted property replacementForAutomaticDeactivationDate (string)

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

Response:

• Changed property data (array)
  • Changed items (object Account)
    • Added property companyEntityExternalReference (string)
    • Deleted property companyAccountExternalReference (string)

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

Response:

• Changed property data (array)
  • Changed items (object CardContract)
    • Changed property cards (array)
      • Changed items (object Card)
        • Added property logoReference (string)
        • Added property dispatchCode (string)
        • Added property automaticDeactivationDate (string)
        • Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/accounts

Response:

• Changed property data (array)
  • Changed items (object Account)
    • Added property companyEntityExternalReference (string)
    • Deleted property companyAccountExternalReference (string)

GET /issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/card-contracts

Response:

• Changed property data (array)
  • Changed items (object CardContract)
    • Changed property cards (array)
      • Changed items (object Card)
        • Added property logoReference (string)
        • Added property dispatchCode (string)
        • Added property automaticDeactivationDate (string)
        • Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/customers/{customerReference}/accounts

Response:

• Changed property data (array)
  • Changed items (object Account)
    • Added property companyEntityExternalReference (string)
    • Deleted property companyAccountExternalReference (string)

GET /issuers/{issuerId}/customers/{customerReference}/card-contracts

Response:

• Changed property data (array)
  • Changed items (object CardContract)
    • Changed property cards (array)
      • Changed items (object Card)
        • Added property logoReference (string)
        • Added property dispatchCode (string)
        • Added property automaticDeactivationDate (string)
        • Deleted property replacementForAutomaticDeactivationDate (string)

POST /issuers/{issuerId}/contracts/search

Response:

• Changed property data (array)
  • Changed items (object Contract)
    • Added property contractClosedByProductChange (object)
    • Added property contractCreatedFromProductChange (object)
    • Deleted property productChangeInformation (object)
    • Changed property accounts (array)
      • Changed items (object Account)
        • Added property companyEntityExternalReference (string)
        • Deleted property companyAccountExternalReference (string)
    • Changed property cardContracts (array)
      • Changed items (object CardContract)
        • Changed property cards (array)
          • Changed items (object Card)
            • Added property logoReference (string)
            • Added property dispatchCode (string)
            • Added property automaticDeactivationDate (string)
            • Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/customers/external-customers/{issuerCustomerExternalReference}/contracts

Response:

• Changed property data (array)
  • Changed items (object Contract)
    • Added property contractClosedByProductChange (object)
    • Added property contractCreatedFromProductChange (object)
    • Deleted property productChangeInformation (object)
    • Changed property accounts (array)
      • Changed items (object Account)
        • Added property companyEntityExternalReference (string)
        • Deleted property companyAccountExternalReference (string)
    • Changed property cardContracts (array)
      • Changed items (object CardContract)
        • Changed property cards (array)
          • Changed items (object Card)
            • Added property logoReference (string)
            • Added property dispatchCode (string)
            • Added property automaticDeactivationDate (string)
            • Deleted property replacementForAutomaticDeactivationDate (string)

GET /issuers/{issuerId}/customers/{customerReference}/contracts

Response:

• Changed property data (array)
  • Changed items (object Contract)
    • Added property contractClosedByProductChange (object)
    • Added property contractCreatedFromProductChange (object)
    • Deleted property productChangeInformation (object)
    • Changed property accounts (array)
      • Changed items (object Account)
        • Added property companyEntityExternalReference (string)
        • Deleted property companyAccountExternalReference (string)
    • Changed property cardContracts (array)
      • Changed items (object CardContract)
        • Changed property cards (array)
          • Changed items (object Card)
            • Added property logoReference (string)
            • Added property dispatchCode (string)
            • Added property automaticDeactivationDate (string)
            • Deleted property replacementForAutomaticDeactivationDate (string)

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

Request body:

• Changed property addCardsAccounts (object CreateConsumerContractRequest.AddCardsAccounts)
  • Changed property cardContracts (array)
    • Changed items (object CreateConsumerContractRequest.CardContract)
      • Added property techAndAppModelReference (string)
• Changed property contract (object CreateConsumerContractRequest.Contract)
  • Changed property cardContracts (array)
    • Changed items (object CreateConsumerContractRequest.CardContract)
      • Added property techAndAppModelReference (string)

Response:

• Changed property data (object CreateConsumerContractResponse)
  • Changed property contract (object CreateConsumerContractResponse.Contract)
    • Changed property cardContracts (array)
      • Changed items (object CreateConsumerContractResponse.CardContract)
        • Added property originalCardContractIdentifier (object)
        • Added property changedCardContractIdentifier (object)

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

Request body:

• Changed property cardContracts (array)
  • Changed items (object CreateConsumerContractRequest.CardContract)
    • Added property techAndAppModelReference (string)

Response:

• Changed property data (object AddCardsAccountsResponse)
  • Changed property contract (object CreateConsumerContractResponse.Contract)
    • Changed property cardContracts (array)
      • Changed items (object CreateConsumerContractResponse.CardContract)
        • Added property originalCardContractIdentifier (object)
        • Added property changedCardContractIdentifier (object)

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

Request body:

• Changed property cardContracts (array)
  • Changed items (object CreateConsumerContractRequest.CardContract)
    • Added property techAndAppModelReference (string)

Response:

• Changed property data (object AddCardsAccountsResponse)
  • Changed property contract (object CreateConsumerContractResponse.Contract)
    • Changed property cardContracts (array)
      • Changed items (object CreateConsumerContractResponse.CardContract)
        • Added property originalCardContractIdentifier (object)
        • Added property changedCardContractIdentifier (object)

Step – 1 : Get the reach details :

Reach details provides list of APIs needs to be used for this scenario and mandatory fields needs to be passed for successful API call towards ASPSP mock.

Call the reach API – GET /aspsp. Get the ASPSP details with Name = “Payment Redirect” and the ASPSP ID = “20100”, which has to be used to initiate the payment with redirect mode of authorisation and other further payment related requests.

Remark : Details of reach information provided in developer portal are limited and informational purpose to give initiating party (user) an idea about how reach information looks like. Initiating party (user) can skip this step and use specified ASPSP ID for the scenario to try out.

Step – 2 : Initiate the payment :

Call the POST /payments API with mandatory fields in request header and body. In response of POST /payments, initiating party (user) will receive payment ID, ASPSP redirect link to authorise the initiated payment and link to call GET /payments/status API to get the status of the initiated payment.

If GET /payments/status endpoint has been called before user provides his / her approval, initiating party (user) will receive payment status = “Open” from the ASPSP Mock in response.

Step – 3 : Authorise or Cancel the payment at ASPSP Mock :

With ASPSP redirect link received in response of POST /payments, customer (PSU) will get redirect to ASPSP Mock GUI login page. On this login page, customer (user) can provide dummy credential details as this is example purpose only. Once customer (PSU) provides his / her dummy credentials, he / she will be redirected to ASPSP Mock GUI page with “Approve” & “Deny” buttons to authorise or cancel the payment.

If customer (PSU) “Approve” the payment, payment will get initiated with the ASPSP Mock and customer (PSU) will redirect back to initiating party (user).

If customer (PSU) “Deny” the payment, ASPSP Mock will reject the initiated payment and customer (PSU) will redirect back to initiating party (user).

Remark : GUI page of ASPSP Mock to approve or deny the payment is just a demo purpose. Actual ASPSP GUI page to approve or deny the payment may vary based on ASPSP.

Step – 4 : Get the payment status :

Call the GET /payments/status API to get the latest payment status from ASPSP Mock.

If payment is authorised by customer (PSU), initiating party (user) will receive payment status = “Settlement Completed” as final payment status.

If payment is deny by customer (PSU), initiating party (user) will receive payment status = “Cancelled” as final payment status.

Remark : Payment status provided for this scenario is just to guide initiating party (user) for payment initiation process. Actual payment status may vary based on scenario from actual ASPSP.

Sequence Diagram :

Below you'll find a list of Payment Initiation Service (PIS) scenarios. Each scenario includes a separate page including a step by step description of the steps to complete the scenario. You can choose a scenario by providing the corresponding ASPSP ID in the request, which initiates the payment.

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

You can use the sandbox:

• On the API reference page (only for registered users, look for the 'try' button)

• With a tool like Postman

These pages describe the components from the Open Banking API version 3 which are used to initiate an iDEAL 2.0 payment. Some sections are based on the iDEAL 2.0 implementation guide from Currence, the iDEAL scheme holder.

Terminology

The terminology used in this document is based on the Payment Service Directive 2.

Open Banking API features for iDEAL payments

Standard iDEAL payments:

• Payment without profile recognition enables PSUs to pay with iDEAL without the need of a registered profile, by means of a manual bank selection or QR code, offered on an iDEAL payment page. See: sequence diagram: example of a flow without profile recognition. On the Transaction Flow page.
• Prefill preferred bank and IBAN for iDEAL payments: The PSU's iDEAL profile can be recognized by using the PsuId which the Open Banking Service can match to iDEAL debtor token, this allows the Initiating Party to immediately present the PSU with his preferred IBAN, and redirect the PSU to his preferred ASPSP (with preferred IBAN pre-selected). Upon future visits, the Initiating Party can retrieve and/or make use of the PSU’s payment preferences in the iDEAL transaction. See: sequence diagram: example of a flow with profile recognition. On the Transaction Flow page.

Fast Checkout iDEAL payment:

• Prefill address and contact details for iDEAL payments: The iDEAL Fast Checkout function allows the PSU to share his centrally stored address and contact details with Initiating Party upon request. This means that PSUs, for example, do not have to enter their address details each time they shop at a different Initiating Party. See: sequence diagram: Fast Checkout. On the Transaction Flow page.

Ecosystem Overview

The Open Banking Services, marked in green, is provided by Worldline

.

Payment processing consists of several main steps, visible in the diagram and explained in dedicated chapters:

1. Payment Preparation

2. Payment Initiation

3. Payment Authorisation

4. Payment Execution

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

• Using Worldline Open Banking functions directly. This allows you to control the user experience, but will require more integration effort due to various combinations of payment flows.

• Using ready-to-go components (Bank Selection Interface and Push Notification). This will provide you with a streamlined integration due to a set of (white labeled) screens which support Bank selection and guides users through the payment steps and push notifications that you will receive whenever payment status changes.

Both integration options can also be combined.

Once you finished your implementation we recommend to go through the list of suggested testing scenarios