BNP Paribas Developerhub leasingsolutions : API Principles

Style and format

API Style

All API exposed on this portal use REST/JSON over HTTPs. Their specifications are compliant with OAS V3.1, provided in YAML format.

Data Format

By default, any reference data (such as dates, currencies, countries...) is exchanged in a format compliant with international standards. Exceptions, if any, will be highlighted in the documentation.

Security and authentication

The communication with the BPLS API portal is secured through TLS 1.3.

Authentication and authorization are managed through mTLS/OAuth2.

The certificate from each consumer of BPLS API must be registered before any access (contact us for more details).

Partner onboarding

Prerequisites to onboard a new partner on LaaS (to be done by BPLS):

Define and share the partner identifier (to use on registering for notification)
Share the programs and product codes available (with corresponding financing parameters, such as the duration, installment periodicity...) with the partner
Synchronize the point of sales with the partner
Setup the partner catalog synchronization process
Setup the BPLS rates or coefficients synchronization process

The standard BPLS process to onboard a new client on the API gateway also applies:

The partner provide their client certificate (preferred format: PEM) for registration
BPLS shares their certificate, private key and CA root certificate, for each environment: client.crt, client.key, ca.crt
BPLS shares the required information
- API gateway host: https://uat.leasingsolutions.api.staging.bnpparibas (UAT) or https://leasingsolutions.api.bnpparibas (production)
- API token endpoint: https://uat.leasingsolutions.api.staging.bnpparibas/auth/oauth/v2/token (UAT) or https://leasingsolutions.api.bnpparibas/auth/oauth/v2/token (production)
- client_id and client_secret to retrieve an OAuth2 token from one of the above endpoints (the scope and grant_type are always oob and client_credentials, respectively)
Example curl command to retrieve a token: curl --cert client.crt --key client.key --cacert ca.crt -X POST
'https://uat.leasingsolutions.api.staging.bnpparibas/auth/oauth/v2/token?client_id=xxxx&client_secret=xxxx&scope=oob' -d 'grant_type=client_credentials'
Example curl command to access an API operation with the retrieved token (token_to_be_put_here): curl --cert client.crt --key client.key --cacert ca.crt -X GET 'https://uat.leasingsolutions.api.staging.bnpparibas/base_path/resource' -H 'Authorization: Bearer token_to_be_put_here'

Lifecycle

By default, all API presented on the developer portal comply with the following principles regarding their lifecycle.

Definitions

A minor version change means that the new version is backward compatible with the previous one, its adoption does not require any action from the partner.
A major version change means that the new version breaks backward compatibility, its adoption requires the partner to adapt its usage of the new API.

Principles

A communication channel is setup for BPLG to deliver all news related to its API. The partner provides the e-mail addresses of the desired recipients. All changes made on the API are also reported on the BPLG developer portal.
At any time, only two major versions of an API are live in production and only one of them is considered “current”, the other one being “deprecated”.
On the introduction of a new minor version, BPLG provides it on its testing environment for one month, in order for the partner to ensure it remains compatible with its platform. After this delay, the new minor version replaces the previous one in the production environment.
On the introduction of a new major version, BPLG provides it on its testing environment for one month. After this delay, it is promoted to the production environment as the “current” version, the older one being immediately deprecated. One year after the initial delivery on the testing environment, at the latest, the older version is retired.
A new major version will never be considered as long as all clients have not migrated to the latest one available, unless its deprecation period mentioned above has expired and it is forcibly retired.

Technical requirements

Headers

x-request-id: for traceability purpose, we require that this header is provided for any API call. It should be populated with a standard UUID (compliant with RFC 9562).

SLA

The API gateway is strategic for BNP Paribas Group, therefore it is treated with the highest level of continuity ("extreme"). In case of an incident, the contractual commitment include an RTO of 2 hours and RPO of 1 day.

Each API has its own limitations, especially due to their implementation, therefore specific SLA levels are detailed whenever they differ from the above norm.

It should be noted that a few API rely on systems that are not available 24x7. Until a migration to always-on systems is finalized, the documentation will mention the unavailability periods on the API concerned.