Backend integration

Cloud-Authentication integration foresee that the developers integrate their backend infrastructure with the SoftPos-MobilePOS platform in app2app mode via the B2B channel. The described APIs allow secure interaction with Nexi’s systems for managing enrollment flows, authentication, and payment initialization using SoftPOS and mPOS terminals. The infrastructure relies on secure data exchange using MTLS (Mutual TLS) and client assertions that are signed and encrypted according to the JWE (RFC 7516) and JWT (RFC 7519) standards, ensuring maximum security and regulatory compliance.

Each application is required to generate and upload a CSR (Certificate Signing Request) through the posweb.nexi.it portal, in order to obtain a certificate signed by Nexi. This certificate is mandatory to perform MTLS calls to the B2B endpoints, which are available in both staging and production environments.

The API calls require the initial retrieval of an access token via client credentials, followed by the ability to retrieve the JWKS public keys, which are necessary to encrypt the assertions. The main call, a PAR (Pushed Authorization Request), follows the RFC 9126 standard and securely initiates the app-to-app enrollment flow through a temporary request_uri.

This documentation includes expected structure of the assertions, required parameters, and certified dependencies between the backend, SDK, and Nexi portal. The goal is to ensure a seamless and secure integration into the SoftPos ecosystem.

CSR

It’s mandatory to create and upload a CSR in the web portal posweb.nexi.it, in order to follow the authentication process required.

openssl req \    -nodes \    -newkey rsa:2048 \    -keyout NOMEAPP.key \    -out 
NOMEAPP.csr \    -subj '/CN=NOMEAPP/O=NEXI/OU=API Security - 
STAGING/L=Milano/C=IT/' \    -addext 'extendedKeyUsage=clientAuth'

In the meanwhile, a private key is created .key

Once the CSR upload is compleated, Nexi will proceed to sign the certificate and send it via e-mail to the developer’s adress. The certificate will be in the body of the email in .p7b format; the developer has to send this certificate in .pem format to Nexi internal referent. By following a methond to convert the certificate from .p7b to .pem

openssl pkcs7 \    -print_certs \    -in NOMEAPP.p7b \    -out NOMEAPP.pem

The developer will be informed once the process has ended.

Please be aware that the same process is required both for production and staging environment.

FQDN

• STG: https://stgb2bsoftpos.nexigroup.com • PROD: https://b2bsoftpos.nexigroup.com

API TOKEN B2B DA BE MERCHANT (B2B)

This API is on B2B channel, therefore has to be called from the merchant BE in MTLS through developer certificate.

curl --request POST \ 
--url <FQDN>/softpos/appenrollment/token \ 
--header 'Content-Type: application/x-www-form-urlencoded' \ 
--data grant_type=client_credentials \

{ 
"access_token": "<BE_MERCH_TOKEN>", 
"token_type": "Bearer", 
"expires_in": 3600

Client id (ID Client) and client secret (Secret) are the data linked to the app logic created on the web portal posweb.nexi.it

The token duration is one hour (3600 s)

ENDPOINT JWKS (B2B)

This API is on B2B channel, therefore has to be called from the merchant BE in MTLS through developer certificate.

This API represent the endpoint to retrive public key to encrypt the client_assertions requested in PAR API And payment_assertion sign through SDK.

curl --request GET --url <FQDN>/softpos/par/jwks.json

CHIAMATA PAR (B2B)

This API is on B2B channel, therefore has to be called from the merchant BE in MTLS through developer certificate. This API follows this standard RFC 9126.

curl --request POST \ 
--url <FQDN>/softpos/as/par \ 
--header 'Authorization: Bearer <BE_MERCH_TOKEN>' \ 
--header 'content-type: application/x-www-form-urlencoded' \

{ 
"request_uri": "<REQUEST_URI>", 
"expires_in": 90 
}

<APP_ID> e <APP_REDIRECT_URI> these parameters are set during app logic creation on the portal

Please keep in mind that these parameters must be equal both in the BE and SDK setting

could have the parameters: openid oidc email profile phone address. ( “oidc” is enough)

<CLIENT_ASSERTION> is a JWE (cfr. RFC 7516), sign with developer certificate and then encrypted with the key Endpoint JWKS.

The plaintext of the <CLIENT_ASSERTION> should be:

{ 
"appId": "<APP_ID>", 
"pointOfSale": "<ID_PUNTO_VENDITA>", 
"terminal_ids": ["<TID_SOFTPOS>", "<TID_MPOS>"],

"terminal_ids" will have a list of di 1 o 2 TID depending if the merchant purchased one SoftPOS and one MPOS a "iss", "sub", "aud", "iat", "exp" e "jti" are claim standard defined here RFC 7519. "aud": "<SOFTPOS_B2B>" represent the FQDN B2B where the operation has to be performed (stg or prod)

Username_merchant has to be an e-mail format, unique for single TID

In the response a <REQUEST_URI> is provided , mandatory to finalize the enrollment process. <REQUEST_URI> will have this format: ex. urn:softpos_a86dd649-3a0d-4c0c-ad9e-c0aa58058d18