Credit Insight
NOTE : the sandbox environment is unavailable for this API.
NOTE : the sandbox environment is unavailable for this API.
This API reference will explain how to integrate the new version of Worldline's Credit Insights products.
All APIs are returning a JSON-encoded response and are organized around REST. It uses standard HTTP response codes.
This section will describe Worldline concepts related to the data model and some basic information on the APIs. Below are some definitions:
Resource | Definition |
Organization | As a client, you are part of an Organization which is related to your company. |
Project | Your Organization can own several Worldline projects. Each one of them represents a set of Worldline Products and configurations. |
Aggregator | An aggregator is an AISP (Account Information Service Provider) able to fetch banking data from financial institutions. |
Connector | A connector is a piece of software which is made to communicate between a third-party technology provider and Worldline. |
Customer
: represents a user able to connect/aggregate their bank accounts. It is unique for your organization, your project and your "custom identifier" (represents your internal reference). Each Customer
has:
Analysis
. One Analysis
contains a score
and a creditInsights
results.Account
. Each Account
has zero, one or many Transaction
API methods that are returning more than one document share the same structure:
resources
: contains the list (or a subset) of requested documentspagination
:
first
: contains the first page URLlast
: contains the last page URLnext
: contains the next page URLprevious
: contains the previous page URLtotalPages
: represents the total number of pagestotalResources
: represents the total number of resourcesOur APIs use a page-based pagination system and accept two query parameters:
limit
: maximum number of resources returned. The default value is set to 200page
: number of the pageThe list below describes all possible errors. It is always returned as a JSON:
code
: a machine readable code.message
: a human readable error message.status
: the HTTP status code
HTTP status | Code | Description |
---|---|---|
400 | MISSING_PARAM |
A required param is missing |
400 | BAD_REQUEST |
A param is not respecting the correct format |
401 | UNAUTHORIZED |
The Authorization header is wrong or is missing |
403 | FORBIDDEN |
You cannot access the API |
404 | NOT_FOUND |
The called API does not exist |
404 | UNKNOWN_ENTITY |
The provided identifier has not been found |
422 | ALREADY_EXISTS |
The entity you are trying to create already exists |
500 | INTERNAL_SERVER_ERROR |
An internal error occurred. |
This API is currently in Beta
This API will allow you to initiate a payment using multiple payment products. This API is currently in development. Initially the following payment products will be supported:
Our unified API facilitates the initiation of different types of credit transfers, such as standard same-day payment, standard instant payment, future payment, multiple payment or payment in batches for e.g. salary payments or invoice payments and the initiation of standing orders or recurring payments.
Depending on the payment product and the ASPSP (debtor bank) the consent of the Payment Service User can be arranged in different ways. The TPP solution makes a distinction between the Redirect, Decoupled and Embedded flow. The flows are visible in sequence diagrams below. These are just examples, a specific ASPSP might require other steps. The TPP solution will always indicate in the responses toward the Initiating party which step has to be performed next.
As an additional service the TPP solution can hide some of the complexity by provide a user interface to support the consent retrieval. From the Initiating Party perspective it will then always be a redirect flow.
What is Account Information Service and how do i get started?
What is Account information?
Account Information Service (AIS) is one of the services established by the Payment Services Directive 2 (PSD2) and aimed to simplify the retrieval of account information. The PSD2 allows Third Party Providers (TPPs) access to the bank's accounts to initiate a payment (PIS) or retrieve account information (AIS) after the account holder (PSU) has given his consent to the TPP.
A payer (PSU) has to consent to a TPP for account information to initiate a AIS request.
Ready to connect?
Using this scenario initiating party (user) can request to revoke a consent given by customer (PSU). When this endpoint is called the TPP solution will also try to revoke the consent at ASPSP side.
If this is successful the status of the consent will be changed to ‘Revoked’.
If it’s not possible to revoke the status at the ASPSP side the status of the consent will be set to ‘RevokedAtTpp’, The consent might still be active on the ASPSP side bit will no longer be used by the TPP solution.
For this scenario, it has been considered that consent has been revoked successfully at ASPSP Mock side.
Take the following steps to complete this scenario.
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 = “AIS Delete Consents” and the ASPSP ID = “20101”, which has to be used to initiate the consent with redirect mode of authorisation and other further 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. User can get the ASPSP ID for appropriate scenario from "Scenario Guideline" page or from the list of "Account Information Services Scenarios" page.
Step – 2 : Acquire customer’s (PSU) consent :
Call the POST /consentextended API to obtain customer’s (PSU) consent. In response of POST /consentextended, initiating party (user) will receive consent ID, ASPSP redirect link to authorise the initiated payment and link to call GET /consent/status API to get the status of the consent.
If GET /consents/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 consent at ASPSP Mock :
With ASPSP redirect link received in response of POST /consentextended, customer (PSU) will get redirect to ASPSP Mock GUI login page. On this login page, customer (user) can enter any username and password 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 reject the consent.
If customer (PSU) “Approve” the consent, consent will be created with the ASPSP Mock and customer (PSU) will redirect back to initiating party (user).
If customer (PSU) “Deny” the consent, ASPSP Mock will reject the consent and customer (PSU) will redirect back to initiating party (user).
Remark : GUI page of ASPSP Mock to approve or deny the consent is just a demo purpose. Actual ASPSP GUI page to approve or deny the consent may vary based on ASPSP.
Step – 4 : Get the consent status :
Call the GET /consents/status API to get the latest consent status from ASPSP Mock.
If consent is authorised by customer (PSU), initiating party (user) will receive consent status = “Authorised”.
If consent is deny by customer (PSU), initiating party (user) will receive consent status = “Rejected” as final consent status.
Remark : Consent status provided for this scenario is just to guide initiating party (user) for consent process. Actual consent status may vary based on scenario from actual ASPSP.
Step – 5 : Delete the consent :
If consent status = “Authorised”, call the Delete /consents API to revoke the consent.
Step – 6 : Get the consent status :
Call the GET /consents/status API to get the latest consent status from ASPSP Mock.
If consent is revoked successfully by ASPSP Mock, initiating party (user) will receive consent status = “Revoked” as final consent status.
Remark : Consent status provided for this scenario is just to guide initiating party (user) for consent process. Actual consent status may vary based on scenario from actual ASPSP.
Sequence Diagram :
Some ASPSPs do not provide paginated transactions response. In those cases it isn’t possible to predict the number of transactions to be received in response of a GET transactions request.
Even if the ASPSP is supporting paginated responses it might be possible that response on the GET transactions request contains a download link only and no transactions, if the number of transactions is considered too high. In this cases or if the bank isn’t giving the response instead of JSON in CAMT format for example, the TPP solution response on the GET transactions will have a download link instead of a set of transactions.
By calling that download link, the response will be given in a streamed JSON structure starting the stream of transactions already before all transactions are downloaded from the ASPSP. If the bank provides the transactions in a non-JSON format the transactions are converted to JSON on the fly by TPP solution.
Processing flow for this scenario is similar to described in “AIS with Redirect Authorisation + Accounts + Balances + Transactions (With Date filter only)” section with addition of GET /download/transactions API to be called by initiating party (user).
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 = “Account information redirect + Download transactions” and the ASPSP ID = “20102”, which has to be used to initiate the consent with redirect mode of authorisation and other further 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. User can get the ASPSP ID for appropriate scenario from "Scenario Guideline" page or from the list of "Account Information Services Scenarios" page.
Step - 2 : Obtain customer's (PSU) consent to access accounts information :
Call the POST /consentextended API to obtain customer's (PSU) consent. In response of POST /consentextended, initiating party (user) will receive consent ID, ASPSP redirect link to authorise the consent and link to call GET /consent/status API to get the status of the consent.
Below are some consent related functionalities initiating party (user) can try out.
Permissions (Array) {[ "Accounts", "Balances", "Transactions" ]}
Initiating party (user) can request permissions in below combination based on customer's (PSU) request.
If GET /consents/status endpoint has been called before user provides his / her approval, initiating party (user) will receive consent status = "Open" from the ASPSP Mock in response.
Step - 3 : Authorise or Cancel the consent at ASPSP Mock :
With ASPSP redirect link received in response of POST /consentextended, customer (PSU) will get redirect to ASPSP Mock GUI login page. On this login page, customer (PSU) can provide dummy credential details as ASPSP GUI page is example purpose only. Once customer (PSU) provides his / her dummy credentials, he / she will be rediereted to ASPSP Mock GUI page with "Approve" & "Deny" buttons to authorise or reject the consent.
If customer (PSU) "Approve" the consent, consent will be created with the ASPSP Mock and customer (PSU) will redirect back to initiating party (user).
If customer (PSU) "Deny" the consent, ASPSP Mock will reject the consent request and customer (PSU) will redirect back to initiating party (user).
Remark : GUI pages of ASPSP Mock for customer login and to authorise the consent is just a demo purpose. Actual ASPSP GUI pages may vary based on acutal ASPSP.
Step - 4 : Get the consent status :
Call the GET /consents/status API to get the latest consent status from ASPSP Mock.
If consent is authorised by customer (PSU), initiating party (user) will receive consent status = "Authorised".
If consent is deny by customer (PSU), initiating party (user) will receive consent status = "Rejected" as final consent status.
Remark : Consent status provided for this scenario is just to guide initiating party (user) for consent process. Actual consent status may vary based on scenario from actual ASPSP.
Step - 5 : Get the list of accounts :
Once consent is authorised by the customer (PSU), call the GET /accounts API to obtain list of accounts from ASPSP Mock.
Step - 6 : Get balances details for respective account :
Once initiating party (user) obtains list of accounts from ASPSP Mock, call GET /balances API to get the balance details of respective account from ASPSP Mock.
Remark : This is an optional step for this scenario. User can skip this step.
Step - 7 : Get the transaction details for respective account :
After getting list of customer's (PSU) accounts from ASPSP Mock, call the GET /transactions API to retrieve transactions details of respective account from ASPSP Mock. In response, initiating party (user) will receive GET /download/transactions API link.
Step - 8 : Call the GET /download/transactions API :
Call the GET /download/transactions API and in response initiating party (user) will receive streamed JSON structure.
Sequence Diagram :
Using this scenario, initiating party (user) can request transaction data from ASPSP Mock using date & time filter ("dateFrom" & "dateTo" query parameters). This is to let initiating party (user) know that some actual ASPSPs are provides requested transaction data based on date & time.
Step - 1 : Get the reach details :
Reach details provides list of APIs and mandatory fields needs to be used for successful request towards ASPSP mock.
Call the reach API - GET /aspsp. Get the ASPSP details with Name = "Account Information redirect + Transaction datetime filter" and the ASPSP ID = "20116", which has to be used to initiate the consent with redirect mode of authorisation and other further 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. User can get the ASPSP ID for appropriate scenario from "Scenario Guideline" page or from the list of "Account Information Services Scenarios" page.
Step - 2 : Obtain customer's (PSU) consent to access accounts information :
Call the POST /consentextended API to obtain customer's (PSU) consent. In response of POST /consentextended, initiating party (user) will receive consent ID, ASPSP redirect link to authorise the consent and link to call GET /consent/status API to get the status of the consent.
Below are some consent related functionalities initiating party (user) can try out.
Permissions (Array) {[ "Accounts", "Balances", "Transactions" ]}
Initiating party (user) can request permissions in below combination based on customer's (PSU) request.
If GET /consents/status endpoint has been called before user provides his / her approval, initiating party (user) will receive consent status = "Open" from the ASPSP Mock in response.
Step - 3 : Authorise or Cancel the consent at ASPSP Mock :
With ASPSP redirect link received in response of POST /consentextended, customer (PSU) will get redirect to ASPSP Mock GUI login page. On this login page, customer (PSU) can provide dummy credential details as ASPSP GUI page is example purpose only. Once customer (PSU) provides his / her dummy credentials, he / she will be rediereted to ASPSP Mock GUI page with "Approve" & "Deny" buttons to authorise or reject the consent.
If customer (PSU) "Approve" the consent, consent will be created with the ASPSP Mock and customer (PSU) will redirect back to initiating party (user).
If customer (PSU) "Deny" the consent, ASPSP Mock will reject the consent request and customer (PSU) will redirect back to initiating party (user).
Remark : GUI pages of ASPSP Mock for customer login and to authorise the consent is just a demo purpose. Actual ASPSP GUI pages may vary based on acutal ASPSP.
Step - 4 : Get the consent status :
Call the GET /consents/status API to get the latest consent status from ASPSP Mock.
If consent is authorised by customer (PSU), initiating party (user) will receive consent status = "Authorised".
If consent is deny by customer (PSU), initiating party (user) will receive consent status = "Rejected" as final consent status.
Remark : Consent status provided for this scenario is just to guide initiating party (user) for consent process. Actual consent status may vary based on scenario from actual ASPSP.
Step - 5 : Get the list of accounts :
Once consent is authorised by the customer (PSU), call the GET /accounts API to obtain list of accounts from ASPSP Mock.
Step - 6 : Get balances details for respective account :
Once initiating party (user) obtains list of accounts from ASPSP Mock, call GET /balances API to get the balance details of respective account from ASPSP Mock.
Step - 7 : Get the transaction details for respective account :
Call the GET /transactions API to retrieve transactions details of respective account from ASPSP Mock. Initiating party (user) can try out below functionalites of GET /transactions API.
Sequence Diagram :
Customer's (PSU) consent needs to be acquire first to access his / her bank's accounts details. In the Redirect Authorisation approach, the bowser session of the customer (PSU) is redirected from the Initiating Party (user) to the ASPSP Mock. In that case the ASPSP Mock provides all the pages required for authentication (usually username, password). After that the customer (PSU) is redircted to the TPP solution and frm ther back to the Initiating Party (user).
Take the following steps to complete this scenario.
Step - 1 : Get the reach details :
Reach details provides list of APIs and mandatory fields needs to be used for successful request towards ASPSP mock.
Call the reach API - GET /aspsp. Get the ASPSP details with Name = "Account Information redirect + Transaction Date filter" and the ASPSP ID = "20101", which has to be used to initiate the consent with redirect mode of authorisation and other further 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. User can get the ASPSP ID for appropriate scenario from "Scenario Guideline" page or from the list of "Account Information Services Scenarios" page.Account Information Services Scenarios
Step - 2 : Obtain customer's (PSU) consent to access accounts information :
Call the POST /consentextended API to obtain customer's (PSU) consent. In response of POST /consentextended, initiating party (user) will receive consent ID, ASPSP redirect link to authorise the consent and link to call GET /consent/status API to get the status of the consent.
Below are some consent related functionalities initiating party (user) can try out.
Permissions (Array) {[ "Accounts", "Balances", "Transactions" ]}
Initiating party (user) can request permissions in below combination based on customer's (PSU) request.
If GET /consents/status endpoint has been called before user provides his / her approval, initiating party (user) will receive consent status = "Open" from the ASPSP Mock in response.
Step - 3 : Authorise or Cancel the consent at ASPSP Mock :
With ASPSP redirect link received in response of POST /consentextended, customer (PSU) will get redirect to ASPSP Mock GUI login page. On this login page, customer (PSU) can provide dummy credential details as ASPSP GUI page is example purpose only. Once customer (PSU) provides his / her dummy credentials, he / she will be rediereted to ASPSP Mock GUI page with "Approve" & "Deny" buttons to authorise or reject the consent.
If customer (PSU) "Approve" the consent, consent will be created with the ASPSP Mock and customer (PSU) will redirect back to initiating party (user).
If customer (PSU) "Deny" the consent, ASPSP Mock will reject the consent request and customer (PSU) will redirect back to initiating party (user).
Remark : GUI pages of ASPSP Mock for customer login and to authorise the consent is just a demo purpose. Actual ASPSP GUI pages may vary based on acutal ASPSP.
Step - 4 : Get the consent status :
Call the GET /consents/status API to get the latest consent status from ASPSP Mock.
If consent is authorised by customer (PSU), initiating party (user) will receive consent status = "Authorised".
If consent is deny by customer (PSU), initiating party (user) will receive consent status = "Rejected" as final consent status.
Remark : Consent status provided for this scenario is just to guide initiating party (user) for consent process. Actual consent status may vary based on scenario from actual ASPSP.
Step - 5 : Get the list of accounts :
Once consent is authorised by the customer (PSU), call the GET /accounts API to obtain list of accounts from ASPSP Mock.
Step - 6 : Get balances details for respective account :
Once initiating party (user) obtains list of accounts from ASPSP Mock, call GET /balances API to get the balance details of respective account from ASPSP Mock.
Step - 7 : Get the transaction details for respective account :
Call the GET /transactions API to retrieve transactions details of respective account from ASPSP Mock. Initiating party (user) can try out below functionalites of GET /transactions API.
Sequence Diagram :
Some ASPSP requires hybrid payment authorisation for payment processing.
Take the following steps to complete this scenario.
Step – 1 : Get the reach details :
Call the reach API – GET /aspsp. Get the ASPSP details with Name = “Payment Redirect with Embedded – Hybrid flow” and the ASPSP ID = “TBD”, which has to be used to initiate the payment with hybrid 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. User can get the ASPSP ID for appropriate scenario from "Scenario Guideline" page or from the list of "Payment Initiation Scenarios" page.
Step – 2 : Payment initiation and customer authentication :
Initiate the payment : Call the POST /payments API without ASPSP PSU-ID and with other mandatory fields in request header and body. In response of POST /payments, initiating party (user) will receive Payment ID, “AspspRedirectUrl” URL for customer (PSU) authentication at ASPSP Mock & GET /payments/status API link.
Customer Authentication : Customer (PSU) will be redirected to ASPSP Mock GUI page to provide his / her PSU-ID (Customer ID) which is known to the Bank. At this point, customer (PSU) can provide his / her authentication to ASPSP Mock or cancel the payment initiation.
Remark : Customer can provide dummy PSU-ID (Customer ID) to ASPSP Mock.
If GET /payments/status endpoint has been called, initiating party (user) will receive payment status = “Open” from the ASPSP Mock in response.
Step – 3 : Get the payment status and select authentication method :
Get the payment status : Call the GET /payments/status API. If customer cancel the authentication process, ASPSP Mock will respond with payment status = “Cancelled” to initiating party (user). If customer (PSU) authenticated successfully at ASPSP Mock, Mock will respond with list of available SCA methods (if multiple SCA methods available at ASPSP) for the customer (PSU) to choose.
Select authentication method : For this scenario, customer (PSU) need to choose ‘SCARedirect’ method for payment authorisation and initiating party (user) need to call the PUT /payments/authorisations to update the selected SCA method to ASPSP Mock. In response, ASPSP Mock will respond with “ASPSPRedirectURL” for payment authorisation.
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.
Step – 4 : Authorise or Cancel the payment at ASPSP Mock :
With ASPSP redirect link received in response of PUT /payments/authorisation, customer (PSU) will get redirect 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 – 5 : 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 = “SettlementCompleted”.
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 :