General Account Management

General Account Management

Each Account is identified by a unique account Reference generated internally, and optionally by an external reference ”issuerAccountExternalReference”  provided by the issuer - which must be unique per issuer.

A set of APIS are available in order to:

  • Retrieve Account general information
  • Retrieve Account financial information
  • Update account parameters
  • Retrieve account specific information (related contract information, contract owner,..)
  • Schedule new account parameters update in the future
  • Retrieve list of future changes for an Account
  • Cancel future changes for an account by future change reference
  • Retrieve future changes for an account by future change reference
  • Retrieve the history of account updates
  • Create a mandate
  • Cancel a mandate
  • Retrieve list of turnovers for an Account
  • Retrieve corporate contract for an account

Retrieve Account

The "Retrieve account" API allows the account details to be retrieved.

The main input fields are:

  • The issuer ID
  • The account for which the detail is requested: It can be provided by using the account reference or the issuer external account reference

It is also possible to request some additional data by using the embedded fields.

In return, the interface provides generic account information (mainly master data). For credit cards, payment mode, the due amount calculation is provided back.

API links

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

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

Below is an example where the request retrieves the account detail for:

  • Account reference : 12343571015282598154
  • Embedded field: cardContractIdentifiers

GET /api/v2/issuers/1234/accounts/12343571015282598154/contract?embed=cardContractIdentifiers

Response data

{
   "data":" "{
      "        ""issuerId":" ""1234",
      "        ""contractIdentifier":" "{
         "            ""contractReference":" ""REF_MCI_BSW_CNT_216566294",
         "            ""issuerContractExternalReference":" ""LEGACY_REF_MCI_BSW_CNT_216566294""        "
      },
      "        ""issuerBranchCode":" ""NO_BRANCH",
      "        ""cardReleaseOrder":" ""AUTOMATIC",
      "        ""signatureDate":" ""2022-06-14T12:54:58.000+00:00",
      "        ""status":" ""SIGNED",
      "        ""statusDate":" ""2022-06-14T12:54:58.000+00:00",
      "        ""cardContractIdentifiers":" "[
         "            "{
            "                ""cardContractReference":" ""12342000000000242108",
            "                ""issuerCardContractExternalReference":" ""T_1234_CARD_VISA_DEBIT_CLASSIC_SHARE""            "
         }"        "
      ],
      "        ""contractOwnerIdentifier":" "{
         "            ""customerReference":" ""CUS10000243080""        "
      },
      "        ""productIdentifier":" "{
         "            ""issuerProductExternalReference":" ""PDT_1234_VISA_DEBIT_CLASSIC_SHARE",
         "            ""productReference":" ""PDT_1234_VISA_DEBIT_CLASSIC_SHARE""        "
      },
      "        ""rootAccountIdentifier":" "{
         "            ""accountReference":" ""12344635788536057209""        "
      }"    "
   }
}

Update Account Parameters

The "update account parameters" API allows the list of pre-defined parameters (attributes) of an account to be updated.

The main input fields requested by the API are:

  • The issuer ID
  • The account for which updates are required: It can be provided by using the account reference or the issuer external account reference
  • Parameters to be updated

The account information can be initially retrieved by using the retrieve Account API.

The updated parameters should be consistent with the initial product configuration defined in the system (e.g a change of closure calendar is accepted only if the provided calendar reference is allowed in the product definition).

This API is used for example to change the IBAN, closure date.

API links

PATCH /api/v2/issuers/{issuerId}/accounts/{accountReference}

PATCH /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}

PATCH /api/v2/issuers/1234/accounts/12343571015282598154

Request data

{
   "bic":" ""BNKDEBBB"
}

Response data

{
   " ""responseMetadata":" "{
      "        ""correlationId":" ""24ecfdcd-a6dc-42c0-8742-e3bfef392d29",
      "        ""statusMessage":" ""Executed successfully",
      "        ""statusCode": 200,
      "        ""responseDateTime":" ""2022-12-05T11:44:08.917+0100",
      "        ""timeTakenMs": 278 
    
   },
   "    ""data":" "{
      "        ""accountIdentifier":" "{
         "            ""accountReference":" ""12343571015282598154""        "
      }"    "
   }
}

Retrieve Account Owner For An Account

The API allows information on the account owner to be retrieved.

The main input fields are:

  • The issuer ID
  • The account for which information is requested.

It is also possible to request additional data like addresses by using the embedded fields.

The API response contains :

  • either customer information if the account owner is a person
  • or company information if the account owner is a company

API links

GET /api/V2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/account-owner

GET /api/V2/issuers/{issuerId}/accounts/{accountReference}/account-owner

Retrieve Account Guarantor For An Account

The API allows information on the account guarantor to be retrieved.

The main input fields are:

  • The issuer ID
  • The account for which information is requested.

It is also possible to request additional data like addresses by using the embedded fields.

The API response contains :

  • either customer information if the account owner is a person
  • or company information if the account owner is a company

API links

GET /api/V2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/account-guarantor

GET /api/V2/issuers/{issuerId}/accounts/{accountReference}/account-guarantor

Retrieve Financial Information For An Account

The API allows financial information of an account to be retrieved (not relevant for a debit card).

The main input fields requested by the API are:

  • The issuer ID
  • The account for which information is requested.

In response, different information is returned, such as account balance, sum of all operations (scheme operations, fees, ect) posted to the account (accepted amount), current open to buy amount (credit and prepaid accounts only).

API links

GET /api/V2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/balance

GET /api/V2/issuers/{issuerId}/accounts/{accountReference}/balance

Below is an example where the request retrieves the financial information for:

  • Account reference : 12343360952787614799
  • Issuer: 1234

GET /api/v2/issuers/1234/accounts/12343360952787614799/balance

Response data

{
           " ""data":" "{
              "        ""acceptedAmount":" "{
                 "            ""value": 25000,
                 "            ""exponent": 2,
                 "            ""isoCode":" ""EUR""        "
              },
              "        ""accountBalance":" "{
                 "            ""value": 0,
                 "            ""exponent": 2,
                 "            ""isoCode":" ""EUR""        "
              },
              "        ""activeCreditLimitAmount":" "{
                 "            ""value": 1000000,
                 "            ""exponent": 2,
                 "            ""isoCode":" ""EUR""        "
              },
              "        ""authorizedAmount":" "{
                 "            ""value": 0,
                 "            ""exponent": 2,
                 "            ""isoCode":" ""EUR""        "
              },
              "        ""currentCycleStartDate":" ""2022-12-19T14:10:44.000+00:00",
              "        ""externalReservedAmount":" "{
                 "            ""value": 0,
                 "            ""exponent": 2,
                 "            ""isoCode":" ""EUR""        "
              },
              "        ""openToBuy":" "{
                 "            ""value": 975000,
                 "            ""exponent": 2,
                 "            ""isoCode":" ""EUR""        "
              },
              "        ""prevailingOpenToBuy":" "{
                 "            ""value": 975000,
                 "            ""exponent": 2,
                 "            ""isoCode":" ""EUR""        "
              }"    "
           }
        }

Retrieve Contract For An Account

The API enables the contract data for a given account to be retrieved.

API links

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

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

Below is an example where the request retrieves the contract detail for:

  • Account reference : 12343360952787614799
  • Issuer: 1234

GET /api/v2/issuers/1234/accounts/12343360952787614799/contract?embed=accountIdentifiers

Response data

{
   "data":" "{
      "        ""issuerId":" ""1234",
      "        ""contractIdentifier":" "{
         "            ""contractReference":" ""1fe5988a-4aec-418a-9133-acc45e3a2960",
         "            ""issuerContractExternalReference":" ""CONTRACT-202212190053""        "
      },
      "        ""issuerBranchCode":" ""NO_BRANCH",
      "        ""cardReleaseOrder":" ""AUTOMATIC",
      "        ""numberOfFreeCardsMembershipFee": 0,
      "        ""numberOfFreeCardsAccountSetupFee": 0,
      "        ""numberOfFreeCardsPrimaryCardImpacted":" false",
      "        ""signatureDate":" ""2022-12-19T14:10:43.000+00:00",
      "        ""status":" ""SIGNED",
      "        ""statusDate":" ""2022-12-19T14:10:43.000+00:00",
      "        ""accountIdentifiers":" "[
         "            "{
            "                ""accountReference":" ""12343360952787614799",
            "                ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212190053""            "
         },
         "            "{
            "                ""accountReference":" ""12346360178674900361",
            "                ""issuerAccountExternalReference":" ""CHILD_ACCOUNT-202212190053""            "
         }"        "
      ],
      "        ""contractOwnerIdentifier":" "{
         "            ""customerReference":" ""CUS10000355325",
         "            ""issuerCustomerExternalReference":" ""PERSON-202212190053""        "
      },
      "        ""productIdentifier":" "{
         "            ""issuerProductExternalReference":" ""PDT_1234_BSW_Mastercard",
         "            ""productReference":" ""PDT_1234_BSW_Mastercard""        "
      },
      "        ""rootAccountIdentifier":" "{
         "            ""accountReference":" ""12343360952787614799",
         "            ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212190053""        "
      },
      "        ""membershipFeeAnniversaryDate":" ""2023-12-18T23:00:00.000+00:00""    "
   }
}

Schedule New Account Parameters Update In The Future

The API is used to enter the account updates that should be applied on a schedule date.

The main input fields requested by the API are:

  • The issuer ID
  • The account involved by the change: It can be provided by using the account reference or the issuer external account reference
  • The plan date
  • The updates

API links

POST /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/account-future-updates

POST /api/v2/issuers/{issuerId}/accounts/{accountReference}/account-future-updates

Below is an example with a change of IBAN scheduled on March, 1.

  • Account reference : 12343360952787614799
  • Issuer: 1234

POST api/v2/issuers/1234/accounts/12343360952787614799/account-future-updates

Request data

{
           "futureChangeDate":" ""2023-03-01T00:00:00.000Z",
           "    ""iban":" ""DE27999999350209299700"
        }

Response data

{
           "    ""responseMetadata":" "{
              "        ""correlationId":" ""3df539d3-2f17-455d-89a6-2a1d0446106a",
              "        ""statusMessage":" ""Executed successfully",
              "        ""statusCode": 200,
              "        ""responseDateTime":" ""2023-02-02T16:47:20.676+0100",
              "        ""timeTakenMs": 39 
            
           },
           "    ""data":" "{
              "        ""creationDate":" ""2023-02-02T15:47:20.656+00:00",
              "        ""futureChangeDate":" ""2023-03-01T00:00:00.000+00:00",
              "        ""accountIdentifier":" "{
                 "            ""accountReference":" ""12343360952787614799",
                 "            ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212190053""        "
              }"    "
           }
        }

List Future Changes For An Account

The API allows a list of all account updates planned in the future to be retrieved.

The main input fields requested by the API are:

  • The issuer ID
  • The account for which information is requested: It can be provided by using the account reference or the issuer external account reference

It is also possible to request the account updates planned in the past and already processed.

API links

get account future updates

GET /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/account-future-updates

GET /api/v2/issuers/{issuerId}/accounts/{accountReference}/account-future-updates

Below an example of request for:

  • Account: 12343360952787614799
  • Issuer: 1234

GET /api/v2/issuers/1234/accounts/12343360952787614799/account-future-updates?all=false

Response data

{
           "    ""data":" "[
              "        "{
                 "            ""issuerdId":" ""1234",
                 "            ""accountIdentifier":" "{
                    "                ""accountReference":" ""12343360952787614799",
                    "                ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212190053""            "
                 },
                 "            ""futureChangeDate":" ""2023-03-01T00:00:00.000+00:00",
                 "            ""creationDate":" ""2023-02-02T15:47:20.000+00:00",
                 "            ""iban":" ""DE27999999350209299700""        "
              },
              "        "{
                 "            ""issuerdId":" ""1234",
                 "            ""accountIdentifier":" "{
                    "                ""accountReference":" ""12343360952787614799",
                    "                ""issuerAccountExternalReference":" ""ROOT_ACCOUNT-202212190053""            "
                 },
                 "            ""futureChangeDate":" ""2023-12-31T00:00:00.000+00:00",
                 "            ""creationDate":" ""2023-02-02T15:44:23.000+00:00",
                 "            ""iban":" ""DE27999999350209299700""        "
              }"    "
           ]
        }

Retrieve Future Changes For An Account By Future Change Reference

The API allows to get the account updates that have to be applied at a schedule date.

The main input fields requested by the API are:

  • The issuer ID
  • The account involved by the change: It can be provided by using the account reference or the issuer external account reference
  • The future change reference (unique per account)

API links

GET /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/account-future-updates/{futureChangeReference}

GET /api/v2/issuers/{issuerId}/accounts/{accountReference}/account-future-updates/{futureChangeReference}

Retrieve The History Of Account Updates

The API enables the account update history to be retrieved.

The main input fields requested by the API are:

  • The issuer ID
  • The account concerned: It can be provided by using the account reference or the issuer external account reference

API links

GET /api/v2 /issuers/{issuerId}/accounts/{accountReference}/account-history

GET /api/v2 /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/account-history

Below is an example where the request retrieves the contract detail for:

  • Account reference : 12349870392328979979
  • Issuer: 1234

The iban has been modified.

GET /api/v2/issuers/1234/accounts/12349870392328979979/account-history?periodStartDateTime=2022-04-04T00%3A00%3A00Z

Response data

{
   "data":[
      {
         "issuerId":"1234",
         "accountIdentifier":{
            "accountReference":"12349870392328979979"
         },
         "effectiveDate":"2023-01-16T12:52:30.883+00:00",
         "accountHierarchySpecificFields":{
            "fieldName2":"value2",
            "fieldName1":""
         },
         "bic":"DEUTDEFFP71",
         "closureCalendarReference":"C_1234_CLOSURE_PL_24",
         "iban":"DE27100777770209299700",
         "overlimitContribution":"0.0",
         "paymentMode":"AUTOPAYMENT",
         "secondIban":"DE07370400442209465934",
         "selectedModels":[
            {
               "type":"eventFeeModel",
               "reference":"M_1234_EVENTFEE_STATEMENT_ONLY"
            },
            {
               "type":"restrictionModel",
               "reference":"M_1234_RESTR_ROOT_STANDARD"
            },
            {
               "type":"statementModel",
               "reference":"M_1234_STATMT_DEFAULT"
            },
            {
               "type":"debitInterestModel",
               "reference":"M_1234_INTEREST_0890"
            },
            {
               "type":"reimbursementModel",
               "reference":"M_1234_REIMB_TERMINATION_ONLY"
            }
         ],
         "spareChangeSaving":false,
         "accountGuarantorIdentifier":{
            "customerReference":"CUS10000205049"
         }
      },
      {
         "issuerId":"1234",
         "accountIdentifier":{
            "accountReference":"12349870392328979979"
         },
         "effectiveDate":"2022-04-04T16:18:55.144+00:00",
         "accountHierarchySpecificFields":{
            "fieldName2":"value2",
            "fieldName1":""
         },
         "bic":"DEUTDEFFP71",
         "closureCalendarReference":"C_1234_CLOSURE_PL_24",
         "iban":"DE52370400441209465934",
         "overlimitContribution":"0.0",
         "paymentMode":"AUTOPAYMENT",
         "secondIban":"DE07370400442209465934",
         "selectedModels":[
            {
               "type":"eventFeeModel",
               "reference":"M_1234_EVENTFEE_STATEMENT_ONLY"
            },
            {
               "type":"restrictionModel",
               "reference":"M_1234_RESTR_ROOT_STANDARD"
            },
            {
               "type":"statementModel",
               "reference":"M_1234_STATMT_DEFAULT"
            },
            {
               "type":"debitInterestModel",
               "reference":"M_1234_INTEREST_0890"
            },
            {
               "type":"reimbursementModel",
               "reference":"M_1234_REIMB_TERMINATION_ONLY"
            }
         ],
         "spareChangeSaving":false,
         "accountGuarantorIdentifier":{
            "customerReference":"CUS10000205049"
         }
      }
   ]
}

Cancel Future Changes For An Account By Future Change Reference

The API is used to cancel the account updates that should be applied on a schedule date (not yet reached).

The main input fields requested by the API are:

  • The issuer ID
  • The account involved by the change: It can be provided by using the account reference or the issuer external account reference
  • The future change reference (unique per account)
  • The reason of the future update cancellation

API links

POST /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/account-future-updates/{futureChangeReference}/cancel

POST /api/v2/issuers/{issuerId}/accounts/{accountReference}/account-future-updates/{futureChangeReference}/cancel

Update Future Changes For An Account By Future Change Reference

The API is used to modify the account updates that should be applied on a schedule date (not yet reached).

The main input fields requested by the API are:

  • The issuer ID
  • The account involved by the change: It can be provided by using the account reference or the issuer external account reference
  • The future change reference (unique per account)
  • The updates
  • The reason of the future update modification

API links

PATCH /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/account-future-updates/{futureChangeReference}

PATCH /issuers/{issuerId}/accounts/{accountReference}/account-future-updates/{futureChangeReference}

Retrieve List Of Turnovers For An Account

This API returns a list of turnovers with the possibility to return only one type of turnover by providing the turnoverType as query parameter.

For each type of turnover, current turnover and historical data are retuned.

The possible turnovers are :

  • the turnover related to membership fee management (turnoverType=MEMBERSHIP_FEE)

    The turnover :

    • is optional (depends on product configuration)
    • can be used for membership fee reimbursement (if any)
    • is calculated for a period based on the membership fee anniversary date
  • the default turnover (turnoverType=DEFAULT)system.
    • is optional (depends on product configuration)
    • can be communicated to cardholder in statement
    • is used for automatic account setup fee reimbursement, if any
    • is calculated for a period based on Account anniversary date or the contract anniversary date (depends on product configuration)

API links

GET /api/v2/issuers/{issuerId}/accounts/{accountReference}/turnovers

GET /api/v2/issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/turnovers

Create Mandate

The API allows to create a SEPA mandate for the given account by using issuer account external reference or the account reference (generated by WL).

  • For SEPA mandate successful creation in mandate management system, the Iban, Iban owner name and mandate signature date are to be provided. As a result, mandate is created in "Active" status and is ready to be used.
  • It is also possible to attach an existing SEPA mandate (explicitly created in mandate management system in advance) to a given account. To succeed, unique mandate reference (UMR) is to be provided as an input. As a result, mandate is attached if exists in mandate management system and is in "Active" status.

A mandate is an authorization that a debtor gives to a creditor in order to take payments from their customers bank accounts.

API links

POST /api/v2/issuers/{issuerId}/accounts/{accountReference}/create-mandate

POST /api/v2 /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/create-mandate

Cancel Mandate

The API allows to cancel SEPA mandate for the given account by using issuer account external reference or the account reference (generated by WL).

The SEPA mandate can be cancelled immediately or in the future at a date provided by the issuer.

  • For immediate cancellation, mandate is “Revoked” immediately in mandate management system.
  • For scheduled cancellation, mandate is not “Revoked” until the cancellation date is reached in mandate management system.

API links

POST /api/v2/issuers/{issuerId}/accounts/{accountReference}/cancel-mandate

POST /api/v2 /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/cancel-mandate

Retrieve corporate contract for an account

The API allows the corporate contract detail of an account to be retrieved.

The main input fields requested by the API are:

  • The issuer ID
  • The account for which the corporate contract information is requested: It can be provided by using the account reference or the issuer account external reference.

It is also possible to request some additional data, such as list of corporate contract entities, list of all customers, list of all companies, list of corporate employee accounts, root account linked to this corporate contract, by using the embedded fields.

In return, the interface provides the corporate contract details.

API links

GET /api/v2/issuers/{issuerId}/accounts/{accountReference}/corporate -contract

GET /api/v2 /issuers/{issuerId}/accounts/external-accounts/{issuerAccountExternalReference}/corporate-contract

Enable "on this page" menu on doc section
On

Contract Replacement With Product Change

Contract Replacement With Product Change(from product A to product B)

Change The Existing Product By Another One

API Reference

The API can be used to replace a consumer contract (so called 'product change'), created from a certain product, by another consumer contract, created from a different product (e.g. in case of card product upgrade, downgrade).

This replacement or change:

  • must be allowed by the configuration (e.g. transition from product A to product B is configured and allowed)
  • is performed either immediately or in the future (next anticipated card renewal date) depending on the configuration

As a result:

  • Card renewal and replacement are disabled for all cards within the old contract
  • In case of product change in the future, the change is scheduled at the first anticipated card renewal date within the contract, and the product change status is PENDING

When this contract replacement or product change is performed (immediately or at the scheduled date):

  • Product change status is set to PROCESSED
  • The new contract is created from the new product (target product)
  • All cards of the old contract are transferred to the new one depending on business rules (e.g. deactivated/cancelled cards are not transferred)
  • Data such as IBAN are transferred to the new contract (data to be transferred depend on issuer requirements)
  • The closing date of the old contract is set according to the delay configured for the issuer
  • Account set-up fee and membership are reimbursed on old contract if requested

API links

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

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

Force A Pending Product Change

When a product change is scheduled for a consumer contract A, card replacement is blocked for each card of this contract A.

In this case, instead of requesting a card replacement this API allows to anticipate / force the scheduled product change on a consumer contract, identified by its Issuer Contract external reference or its Contract reference.

Also, the card to be replaced, previously permanently blocked (e.g. for lost or stolen reason) after the product change request, can be transferred to the new contract, not in cancelled status but in the status foreseen by the new product.

As a result:

  • Product change status is set to PROCESSED
  • The new contract is created from the new product
  • All cards of the old contract (e.g. contract A) are transferred to the new one depending on business rules (e.g. deactivated/cancelled, permanently blocked cards before the product change request are not transferred
  • Data such as IBAN are transferred to the new contract
  • The closing date of the old contract is set according to the delay configured for the issuer
  • Account set-up fee and membership are reimbursed on old contract if requested

API links

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

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

Cancel A Pending or Scheduled Product Change

The API can be used to cancel a product change for a given consumer contract, identified by either its issuer Contract external reference or its Contract reference:

  • PENDING or already PROCESSED product change
  • The cancellation is possible as long as the original contract is not yet closed (product change already processed).
  • It is possible to request the reimbursement of the fees (membership fee / account setup) already posted on the new contract.
  • It is possible to request cancellation only for the latest product change that was performed for the contracts that are linked each other through a product change (old contracts, new contract)

As a result,

  • In case of cancellation of a pending product change, the product change is not performed.
  • In case of cancellation of a product change already processed, the product change is reversed:
    • the original contract,and its cards will not be closed
    • the new contract and new cards are closed immediately

API links

POST /api/V2/issuers/{issuerId}/contracts/{contractReference}/cancel-change-product

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

Enable "on this page" menu on doc section
On

ob-data-ais-s4

Delete Consent

You can request to revoke account holder's consent. If the revocation is successful, the status of the consent will be changed to ‘Revoked’. If it’s not possible to revoke the consent, the status of the consent will be set to ‘RevokedAtTpp’, meaning the consent might still be active on the bank's side but can't no longer be used by you to retrieve the data.

In this testing scenario, it has been considered that consent has been revoked successfully. Take the following steps to complete this scenario.

Step - 1 : Get the list of connected banks

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

Step - 2 : Initiate consent

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

Step - 3 : Authorise or reject the consent

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

Step - 4 : Get consent status

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

Step - 5 : Revoke consent

  • If consent status = “Authorised”, call the Delete /consents API endpoint to revoke the consent.

Step - 6 : Get consent status

  • Call the GET /consents/status API to get the latest consent status from the mock bank.
  • If consent is revoked successfully, you will receive consent status = "Revoked".

Sequence Diagram

Delete Consent
Enable "on this page" menu on doc section
On

ob-data-ais-s3

Download Transactions

If the banks supports paginated response but the number of transactions is considered too high or if the bank provides the response in CAMT format, it might be possible that the GET transactions response contains a download link only.

Using the link you can download the list of transactions in JSON format. If the bank provides the transactions in a non-JSON format, the transactions are converted to JSON by Worldline.

Processing flow for this scenario is similar to described in “Redirect flow with Date filter only” section with addition of GET /download/transactions API.

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

Take the following steps to complete this scenario.

Step - 1 : Get the list of connected banks

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

Step - 2 : Initiate consent

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

Step - 3 : Authorise or reject the consent

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

Step - 4 : Get consent status

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

Step - 5 : Get list of accounts

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

Step - 6 : Get transaction details

  • Call the GET /transactions API to retrieve transactions details of respective account. 
  • In response, you will receive GET /download/transactions API link.

Step - 7 : Download transactions

  • Call the GET /download/transactions API link  and  receive the list of transactions in JSON format.

Sequence Diagram

AIS Download Transactions
Enable "on this page" menu on doc section
On

ob-data-ais-s2

Redirect flow with DateTime filter

This scenario is similar to the first testing scenario with a slight difference, that the returned transactions are filtered using both date and time parameters ("dateFrom" & "dateTo" query parameters) as we want to bring to your attention that some banks provide requested transaction data based on date & time.

Take the following steps to complete this scenario.

Step - 1 : Get the list of connected banks

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

Step - 2 : Initiate consent 

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

Step - 3 : Authorise or reject the consent 

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

Step - 4 : Get consent status

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

Step - 5 : Get list of accounts

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

Step - 6 : Get balances details

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

Step - 7 : Get transaction details

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

Sequence Diagram

AIS with Redirect authorisation - dateTime

 

Enable "on this page" menu on doc section
On

ob-data-ais-s1

Redirect flow with Date filter only

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

Take the following steps to complete this scenario.

Step - 1 : Get the list of connected banks

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

Step - 2 : Initiate consent

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

Step - 3 : Authorise or reject the consent

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

Step - 4 : Get consent status

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

Step - 5 : Get list of accounts

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

Step - 6 : Get balances details

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

Step - 7 : Get transaction details

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

Sequence Diagram

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

ob-data-ais-sand

List of Account Information Service Scenarios

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

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

You can use the sandbox:

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

 

Enable "on this page" menu on doc section
On

ob-data-ais-api

Consent Initiation

API Reference

Consent scope

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

  • Accounts
  • Balances
  • Transactions 

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

POST Consents

Endpoint: POST /psus/{psuId}/consents

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

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

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

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

 

Data model

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

Multi-level SCA

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

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