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
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
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
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
Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once. The response will be retrieved directly from our system.
API links
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
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
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
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
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
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
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.
Idempotency is managed by the API; that is, if the request with the same WL-Correlation-ID is sent multiple times, it will be executed only once. The response will be retrieved directly from our system.
API links
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
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 (limited to 100), list of all customers (limited to 100), list of all companies (limited to 100), list of corporate employee accounts (limited to 100), root account linked to this corporate contract, by using the embedded fields.
In return, the interface provides the corporate contract details.
API links