How to use the PISP Hub API ?

To utilize the services of the PISP HUB, the Payee must first connect to our API compliant with the ISO 20022 standard. The PISP HUB then handles the interconnection with the PSD2 APIs exposed by the ASPSPs (Account Servicing Payment Service Providers).

The requested transfer can be:

• A classic transfer (SEPA Credit Transfer, with settlement from D+1 to D+3 depending on the business day calendar);
• An instant transfer (SEPA Instant, with settlement occurring within 10 seconds following the validation - consent - of the payment by the Payer).

Depending on the nature of the requested transfer, it can be categorized as:

• Immediate: the transfer will be executed immediately after the Payer's consent;
• Deferred: the transfer will be executed on a future date as defined by the Payee;
• Recurring: the transfer will be repeated a specified number of times identically (same amount) according to a determined schedule.

The nature of the transfer and its timing must be specified in the request sent by the Payee to the PISP HUB and cannot be modified afterwards.

The Payee can either:

• Impose the terms of the transfer;
• Leave this choice to the Payer by adapting their customer journey accordingly.

Each operation is accompanied by references provided by the Payee, which will be carried throughout the exchanges until the transaction is completed and statements are issued, allowing for precise, potentially automated, reconciliation of payments within the Payee's system.

The solution enables the initiation of payment requests to over 95% of bank accounts domiciled in France, and to an increasing number of bank accounts domiciled in various European countries (SEPA zone). Transfers can only be denominated in Euros.

The HUB PISP Services under the microscope

Retrieve the list of reachable institutions and their services 

In cases where the Payee wishes to develop their own bank selection screens, or for any other specific needs requiring this information, they can call a service from the API to retrieve:

• The list of account-holding institutions accessible for initiating a payment request from the HUB PISP;
• The list of supported transfers (SCT and/or SCT Inst) by each of these institutions;

They can also call a dedicated service exposed by the API allowing the retrieval of the logos of these various banking institutions to provide flexibility and responsiveness during a tailored customer journey.

Implementation 

The retrieval of the list of reachable institutions is done via the [Endpoint ACCOUNT SERVICE PROVIDER].

The retrieval of the logos of the groups of reachable institutions is done via the [Endpoint HEAD COMPANY].

Initiate and track a payment 

Once the Payer has chosen their bank, and that bank has been validated and is reachable, a payment initiation request can be issued. The Payee, to initiate a payment request via the HUB PISP API, must provide the following mandatory information:

• The amount and the currency of the payment (Euro only);
• The BIC of the bank or the IBAN of the Payer, if known by the Payee;
• The nature of the requested transfer (SCT or SCT Inst);
• The account to be credited (the IBAN of the Payee's account);
• The references they wish to convey to the account crediting, which will allow them to perform their reconciliation.

In return, the Payee receives a URI of consent communicated by the Payer's bank, which allows redirecting the Payer to their usual banking interface (online banking or mobile application), from where, after authentication, they can choose the account to debit and consent to the payment.

To allow the Payee to track the status of the operation, the HUB PISP returns the following statuses:

• A first level of acknowledgment confirming that the HUB PISP API has successfully taken charge of the payment request;
• A second level of acknowledgment confirming the consent or refusal of the payment by the Payer;
• A third level of acknowledgment confirming the final status of the transfer issued by the Payer's bank, in favor of the Payee's bank. This status will evolve over time until it indicates a final and definitive result of the transfer (issued or rejected).

Note that access to these statuses is done through a system of successive polling of the HUB PISP; return URLs are not supported in this case.

Implementation 

The issuance of a payment initiation request is done via the [Endpoint PAYMENT INITIATION].

The retrieval of the payment initiation status is done via the [Endpoint PAYMENT INITIATION GET STATUS].

Offer the customer the choice of their bank and initiate a payment 

To identify the bank to which the payment request should be sent, the Payee can use a service that allows the Payer to select their bank simply and quickly from a page provided by the HUB PISP.

This page allows for a graphical display of logos, compatible with mobile or PC operating modes, of the institutions accessible through the HUB PISP. The simple selection of their bank by the Payer, from which they wish to proceed with the payment, allows for the initiation of the payment without the need for them to enter their IBAN or banking details, which will remain unknown to the Payee.

This link is generated by the HUB PISP and transmitted to the Payee, who is then responsible for providing it to the Payer by means they deem appropriate (email, SMS, QR code, etc.).

When the Payer has chosen their bank, a payment request (payment initiation) is issued in accordance with what is indicated in the section [Initiate and Track a Payment].

In addition to the statuses of the payment initiation, the returned statuses are supplemented by those of the payment link itself:

• NOT PROCESSED: the link has not been opened by the Payer but is still valid;
• EXECUTED: the link has been opened by the Payer;
• PROCESSED: the Payer has selected their bank from the list presented to them; at this stage, a payment initiation has been issued, the status of which can be consulted via the [Endpoint PAYMENT INITIATION GET STATUS];
• EXPIRED: the link has not been opened by the Payer and has expired.

Note that additional information can be retrieved, such as the date the link was created, the date the link was opened by the Payer, etc.

Implementation 

The provision of the bank selection service followed by the issuance of a payment initiation is done via the [Endpoint PAYMENT LINK].

The retrieval of the status of the payment link and the identifier of the payment initiation, if applicable, is done via the [Endpoint PAYMENT LINK GET STATUS].

The retrieval of the status of the payment initiation itself is done via the [Endpoint PAYMENT INITIATION GET STATUS].

General security principles for APIs

The security of access to APIs by the Client is ensured through the implementation of the following measures:

• All exchanges are secured using TLS with no possibility of exemption;
• For message exchanges, the Client must provide x509 certificates issued by a certification authority that publishes revocation lists accessible 24/7/365. In return, the Client will receive certificates issued by BPCE PS; these certificates are used on both sides to perform mutual authentication of the caller (the Client) and the server (the BPCE PS API) to guarantee the security of the connection between the parties;
• Access to the API requires prior OAuth2 authentication using an identifier (clientID) and a password (clientSecret) provided by BPCE PS during the Client's enrollment;
• Following an authorized access request (via OAuth2), the token assigned and returned to the Client will be used in all subsequent exchanges as long as it remains valid, to identify the message sender.
• Finally, all exchanged messages must be signed using the RSA-SHA algorithm.

These measures aim to ensure the identification and authentication of the Client when using the API, as well as the integrity (SHA) and signature (RSA) of the exchanged messages.