Documentatie testare API-uri PSD2

Documentatie testare API-uri PSD2

1.  Descriere functionalitati produs PSD2-CECAPIC

Dupa logarea pe portal, utilizatorii inregistrati au acces la produsul  PSD2-CECAPIC

Acest produs include API-urile necesare dezvoltarii aplicatiilor TPP cu functionalitati de tip AIS/PIS:

  • PSD2 API-ConsentC: contine operatiile necesare preluarii consimtamantului clientului pentru accesarea conturilor deschise la CEC Bank;
  • PSD2 API-AccountsC: contine operatiile necesare dezvoltarii functionalitatilor AIS (se extrag date despre conturi cu limitarile specificate in consimtamantul clientului);
  • PSD2 API-PaymentsC: contine operatiile necesare dezvoltarii functionalitatilor PIS (se pot initia tranzactii pentru care se solicita autorizarea  clientului) si PIIS (se poate confirma disponibilitatea unei anumite sume in cont in baza unui acord valid de consultare cont).
  • OauthCEC: contine operatiile necesare procedurii SCA de tip Oauth2 pentru autentificare client (PSU) si autorizare consent sau plata (generare cod de acces pentru aplicatie , token de access pentru resurse );

Pentru a accesa/testa API-urile de mai sus, aplicatia TPP trebuie sa subscrie la utilizarea acestora.La apelarea operatiilor din API-uri, sunt necesari parametrii de autentificare aplicatie: Client Id si Client Secret. De asemenea, apelarea API-urilor: PSD2 API-ConsentC, PSD2 API-AccountsC, PSD2 API-PaymentsC este  permisa  numai daca se completeaza parametrul de header Tpp-Signature-Certificate al fiecarui apel cu certificatul EIDAS al TPP de  forma :

-----BEGIN  CERTIFICATE-----

MIID5DCCAsygAwIBAgIDUFNEMA0GCSqGSIb3DQEBBQUAMIGIMSEwHwYJKoZIhvcN

……………………………………………….

U5dUhcNTrqX1M9b6AsiaqBDK+eGATXOZpKYrXhOpUqCJm/drFPGiuw==

-----END CERTIFICATE-----

 

 

II Descrierea fluxului pentru obtinere date conturi client

 

 

3. Transmitere solicitare pentru preluare acord accesare conturi client: creare consent .

Se apeleaza operatia POST /v1/consents din API-ul PSD2 API-Consent. In Header se completeaza obligatoriu: X-Request-ID, X-IBM-Client-Id ,TPP-Redirect-URI si Tpp-Signature-Certificate.

In Body nu trebuie transmise informatii. Continutul consentului va fi stabilit de catre client dupa autentificarea in sistemul  bancii, in interfata de autorizare consent expusa de catre banca.

 

In structura de raspuns, se primeste identificatorul resursei de tip consent nou creata “consentId”, precum si link-ul “scaOAuth” unde sunt furnizate metadatele serverului de autorizare Oauth 2.0 .

Aplicatia TPP trebuie sa redirecteze PSU catre pagina de autentificare a bancii, utilizand endpointul de autorizare furnizat de link-ul scaOAuth.

 

Exemplul de formare a URL-ului pentru Redirect poate fi gasit in atributul “Location” al headerului raspunsului operatiei POST /v1/consents:

Location :

 https://api-test.cec.ro/cec/tpp/oauthcec/oauth2/authorize?

response_type=code

&scope=AIS:43a5a1a0-a456-11ec-b4e2c-00a0800270000

&redirect_uri=https://example.com/redirect

&client_id=28xxxxxxxxxxfe8a3

&code_challenge=<code challenge value>

&code_challenge_method=<code challenge method>

Inainte de utilizare, link-ul din headerul “Location” trebuie completat de catre aplicatia TPP cu valoarea  parametrului code_challenge (PKCE challenge according to cryptographic RFC 7636 - https://tools.ietf.org/html/rfc7636  used to prevent code injection attacks, code_challenge_method= "S256")

 

4. Autentificarea clientului in sistemul bancii

Aplicatia TPP-ului redirecteaza clientul la URL de autorizare format la pasul anterior , unde se deschide fereastra de logare in platforma de autentificare.

Clientul se poate loga folosind  numele de utilizator din aplicatia de Internet Banking-CEC Online si codul generat de dispozitivul de generare coduri sau de aplicatia eToken.

 

5. Preluare acord client pentru consultare date conturi

Dupa logarea cu succes si identificarea clientului logat, apare fereastra de preluare acord pentru accesarea conturilor de catre aplicatia TPP. 

In functie de permisiunile acordate de catre client pentru fiecare cont de plati din lista, aplicatia TPP-ului va putea vizualiza ibanurile conturilor si va avea acces la vizualizarea soldurilor, respectiv a listei de tranzactii

 

Daca se apasa “Nu sunt de acord!’ , la adresa de redirect a aplicatiei TPP se transmite “error=acces_denied”

6.a. Generare cod acces pentru aplicatie

In urma permiterii accesului la conturi de catre client, la adresa de redirect furnizata de aplicatia TPP, se transmite codul de acces pentru aplicatie (“code”).

7. Obtinere token de acces in vederea consultarii conturilor

Aplicatia TPP va furniza codul de acces de mai sus in schimbul unui token de access la resurse (Bearer Token), prin apelarea metodei POST /oauth2/token de la URL-ul indicat in metadata “token_endpoint”, in scopul “AIS:consentId” (acelasi scop continut in codul de acces furnizat la pasul anterior)

Request body trebuie trimis in format x-www-form-urlencoded si trebuie sa contina parametrii de mai jos (valorile exemplificate corespund parametrilor in/out ai operatiei de autorizare prezentata in pasul anterior):

-    grant_type=authorization_code

-    client_id=28xxxxxxxxxxfe8a3

-    code= AAIAlw82ZhTM7wAPbo6580McU6E9n4oJUznpUe8mw6KzB6owuInP5QD2z9NCMngf_xuk9dtl9W3xZln64jnGLuFLCFUnq80DN3CaEGTxfkwE5fp2I17DuxPacZovpRCGplsj7Vfo9lqphLkdxPDVKL3j

-    redirect_uri= https://example.com/redirect

-    scope= AIS:43a5a1a0-a456-11ec-b4e2c-00a0800270000

-    code_verifier=ginfeftejiscu

curl --request POST \

--url https://api-test.cec.ro/cec/tpp/oauthcec/oauth2/token \
--header 'accept: application/json' \
--header 'content-type: application/x-www-form-urlencoded' \
--header 'x-ibm-client-id: 28xxxxxxxxxxfe8a3\
--data 'grant_type=authorization_code&client_id=28xxxxxxxxxxfe8a3&code= AAIAlw82ZhTM7wAPbo6580McU6E9n4oJUznpUe8mw6KzB6owuInP5QD2z9NCMngf_xuk9dtl9W3xZln64jnGLuFLCFUnq80DN3CaEGTxfkwE5fp2I17DuxPacZovpRCGplsj7Vfo9lqphLkdxPDVKL3j&redirect_uri= https://example.com/redirect&scope= AIS:a2308f60-76e3-11eb-9881-0a06001a0000&code_verifier=ginfeftejiscu'

200 OK

{

    "token_type": "bearer",

    "access_token": "AAIkMjg2Yjk1NmYtZDQxMS00OTM4LTljMGUtYmI1ODE1YWZlOGEzIjPNvUaB8KIeDgPgFbjI7AANcFyG-HCnV-hiqPVlo17k5DjRoCB7PSv8--qKI1JuneC52uXWAgU7iE1OA_NYC6JJTRYtYBi6I2DL88f4_uxormO0Bi6zBj6lld1D3rtNI9uT0dUAL2WHk5L5VjhJFQ",

    "expires_in": 3595,

    "consented_on": 1614240924,

    "scope": "AIS:43a5a1a0-a456-11ec-b4e2c-00a0800270000",

    "refresh_token": "AAJzRQj3N2Wd-3pb005516_i9ISl6ZL3Ut5n1w2gbh8YK5vxjb86zMQcwILT29Dq-4ZNHvcpBSr90uoemjU9LhUgkF0-dpHPTdShGuPJOwi6gCbfaxD3PSFu-oTgKQzReCKxIOxPldguuu5M7Xquy4NudJ7LDVWRxI52JBNpxtCGYQ",

    "refresh_token_expires_in": 2682000

}

 

In raspunsul operatiei POST /oauth2/token, se gaseste valoarea access token necesara apelurilor API-urilor PSD2 API-AccountsC,i PSD2 API-ConsentC si operatiei POST /v1/funds-confirmations din PSD2 API-PaymentsC. De asemenea, se precizeaza valoarea refresh_token, cu o perioada de valabilitate corespunzatoare valabilitatii consentului  (max.90 zile), care poate fi utilizat pentru generarea unui nou acces_token fara implicarea PSU.

8. Obtinere refresh_token

Pentru a obtine un nou access_token valid in schimbul refresh_token-ului, se utilizeaza acceeasi operatie POST /oauth2/token, dar cu grant_type=refresh_token, ca in exemplul de mai jos.

curl --request POST \
--url https://api-test.cec.ro/cec/tpp/oauthcec/oauth2/token \
--header 'accept: application/json' \
--header 'content-type: application/x-www-form-urlencoded' \
--header 'x-ibm-client-id: 28xxxxxxxxxxfe8a3\
--data 'grant_type=refresh_token&client_id=28xxxxxxxxxxfe8a3&refresh_token= AAJzRQj3N2Wd-3pb005516_i9ISl6ZL3Ut5n1w2gbh8YK5vxjb86zMQcwILT29Dq-4ZNHvcpBSr90uoemjU9LhUgkF0-dpHPTdShGuPJOwi6gCbfaxD3PSFu-oTgKQzReCKxIOxPldguuu5M7Xquy4NudJ7LDVWRxI52JBNpxtCGYQ

9. Obtinerea datelor despre conturi

Se apeleaza operatia GET /v1/accounts din API-ul PSD2-AccountsC, transmitand in header:

"x-ibm-client-id" :"client_id-ul generat de aplicatia creata pe portal"

"x-Request-ID" : "id de forma: 123e4567-e89b-12d3-a456-426655440000"

 “Authorization”: “acces tokenul de tip Bearer obtinut la pasul anterior”,

“Consent-ID”: “valoarea consentId pentru vizualizare date conturi”,

“TPP-Signature-Certificate”:”certificat EIDAS al TPP cu rol PSP_AI”

 

 

10. Obtinere detalii cont

Se apeleaza operatia GET /v1/accounts/{account-id} din API-ul PSD2-AccountsC  astfel:

In header se trimit:

"x-ibm-client-id" :"client_id-ul generat de aplicatia creata pe portal"

"x-Request-ID" : "id de forma: 123e4567-e89b-12d3-a456-426655440000"

 “Authorization”: “acces tokenul de tip Bearer obtinut la pasul anterior”,

“Consent-ID”: “valoarea consentId pentru vizualizare date conturi”,

“TPP-Signature-Certificate”:”certificat EIDAS al TPP cu rol PSP_AI”

Parametrii:

"account-id" : "Id-ul contului pentru care se cer detalii"

 

Response:

{
    "accounts": [
        {
            "resourceId": "25511978",
            "iban": "RO42CECEQW9898bON9993644",
            "currency": "RON",
            "product": "Cont curent - persoane fizice - LEI",
            "cashAccountType": "CurrentAccount",
            "name": "421642",
            "balances": [
                {
                    "balanceAmount": {
                        "currency": "RON",
                        "amount": 320.02
                    },
                    "balanceType": "closingBooked",
                    "referenceDate": "2022-03-16"
                }
            ],
            "_links": {
                "balances": {
                    "href": "/v1/accounts/25511978/balances"
                },
                "transactions": {
                    "href": "/v1/accounts/25511978/transactions"
                }
            }
        }
    ]
}

11. Obtinere balanta cont

Se apeleaza operatia GET /v1/accounts/{account-id}/balances din API-ul PSD2-AccountsC  astfel:

In header se trimit:

"x-ibm-client-id" :"client_id-ul generat de aplicatia creata pe portal"

"x-Request-ID" : "id de forma: 123e4567-e89b-12d3-a456-426655440000"

 “Authorization”: “acces tokenul de tip Bearer obtinut la pasul anterior”,

“Consent-ID”: “valoarea consentId pentru vizualizare date conturi”,

“TPP-Signature-Certificate”:”certificat EIDAS al TPP cu rol PSP_AI”

Parametrii:

"account-id" : "Id-ul contului pentru care se cer detalii"

 

 Response:

{
    "account": {
        "iban": "RO42CECEQW9898bON9993644",
        "currency": "RON"
    },
    "balances": [
        {
            "balanceAmount": {
                "currency": "RON",
                "amount": "320.02"
            },
            "balanceType": "closingBooked",
            "referenceDate": "2022-03-16"
        }
    ]
}
 
 
 
 
 

12. Obtinere lista tranzactii pe cont

Se apeleaza operatia GET /v1/accounts/{account-id}/transactions din API-ul PSD2-AccountsC  astfel:

In header se trimit:

"x-ibm-client-id" :"client_id-ul generat de aplicatia creata pe portal"

"x-Request-ID" : "id de forma: 123e4567-e89b-12d3-a456-426655440000"

 “Authorization”: “acces tokenul de tip Bearer obtinut la pasul anterior”,

“Consent-ID”: “valoarea consentId pentru vizualizare date conturi”,

“TPP-Signature-Certificate”:”certificat EIDAS al TPP cu rol PSP_AI”

Parametrii:

"bookingStatus" : poate fi: "booked", "pending", "both"

"dateFrom": "data inceput ieterval cautare tranzactii"

"dateTo": "data sfarsit ieterval cautare tranzactii"

"account-id" : "Id-ul contului pentru care se cer detalii"

 

Raspuns:

{
    "account": {
        "iban": "RO42CECEQW9898bON9993644"
    },
    "transactions": {
        "booked": [
            {
                "transactionId": "1174425360",
                "creditorAccount": {},
                "transactionAmount": {
                    "currency": "RON",
                    "amount": -19.8
                },
                "bookingDate": "2021-10-10",
                "valueDate": "2021-10-10",
                "remittanceInformationUnstructured": "Sqpytqlyzqru torqntq-Qsxytqru torqntq nutq lq ssqtuntq tyn sont surunt puntru sontrqstul nr  894414336"
            },
            {
                "transactionId": "1174425359",
                "creditorAccount": {},
                "transactionAmount": {
                    "currency": "RON",
                    "amount": -2.2
                },
                "bookingDate": "2021-10-10",
                "valueDate": "2021-10-10",
                "remittanceInformationUnstructured": "Plqtq ympozyt-Plqtq ympozyt lq ssqtuntq tyn sont surunt puntru sontrqstul nr  894414336"
            },
            {
                "transactionId": "1174425358",
                "debtorAccount": {},
                "transactionAmount": {
                    "currency": "RON",
                    "amount": 22
                },
                "bookingDate": "2021-10-10",
                "valueDate": "2021-10-10",
                "remittanceInformationUnstructured": "Sqpytqlyzqru torqntq-Sqpytqlyzqru torqntq rrutq lq ssqtuntq yn sont surunt puntru sontrqstul nr  894414336"
            },

 

 

13. Obtinere detalii tranzactie

Se apeleaza operatia GET /v1/accounts/{account-id}/transactions/{resourceId} din API-ul PSD2-AccountsC  astfel:

In header se trimit:

"x-ibm-client-id" :"client_id-ul generat de aplicatia creata pe portal"

"x-Request-ID" : "id de forma: 123e4567-e89b-12d3-a456-426655440000"

 “Authorization”: “acces tokenul de tip Bearer obtinut la pasul anterior”,

“Consent-ID”: “valoarea consentId pentru vizualizare date conturi”,

“TPP-Signature-Certificate”:”certificat EIDAS al TPP cu rol PSP_AI”

Parametrii:

"account-id" : "Id-ul contului pentru care se cer detalii"

"resourceId": "Id-ul tranzactiei"

Response:
 
 
{
    "transactions": {
        "booked": [
            {
                "transactionId": "1174425360",
                "creditorAccount": {},
                "transactionAmount": {
                    "currency": "RON",
                    "amount": -19.8
                },
                "bookingDate": "2021-10-10",
                "valueDate": "2021-10-10",
                "remittanceInformationUnstructured": "Sqpytqlyzqru torqntq-Qsxytqru torqntq nutq lq ssqtuntq tyn sont surunt puntru sontrqstul nr  894414336"
            },
            {
                "debtorName": "",
                "debtorAccount": {
                    "iban": ""
                },
                "transactionAmount": {}
            }
        ]
    },
    "account": {
        "iban": "RO42CECEQW9898bON9993644"
    }
}
 

 

 

III. Initierea si autorizarea platilor utilizand operatiile serviciului PSD2 API-PaymentsC

Serviciul PSD2 API-PaymentsC poate fi utilizat de TPP cu rol PISP (certificat EIDAS care include rolul PSP_PI) pentru a initia plati in numele unui client.

Se presupune ca datele despre contul debitor implicat in tranzactie au fost obtinute anterior, de obicei prin utilizarea operatiei GET /v1/accounts din serviciul PSD2 API-AccountsC.

Diagrama fluxului de initiere/procesare plata este prezentata in figura de mai jos:

 

 

In flux se disting urmatorii pasi:

  1. Clientul (PSU) solicita initierea platii in aplicatia TPP. Aplicatia TPP-ului utilizeaza operatia POST /v1/{payment-service}/{payment-product} pentru a transmite catre Banca datele platii solicitate de client.
  2. Serviciul Bancii verifica corectitudinea datelor si memoreaza datele platii, in raspunsul returnat aplicatiei TPP fiind precizat identificatorul platii si link-ul scaOAuth (utilizat pentru determinarea URL-ului interfetei expuse de banca pentru autorizarea platii).
  3. Aplicatia TPP redirecteaza clientul catre interfata de autorizare expusa de banca.
  4. In interfata CEC Bank Authorization Server, clientul este autentificat in sistemul bancii in baza credentialelor de logare in aplicatia Internet Banking-CEC Online.
  5. Dupa autentificarea reusita clientul isi da acordul pentru procesarea platii sau o poate rejecta.
  6. Clientul este redirectat catre aplicatia TPP. Daca plata a fost autorizata de catre client, la adresa de redirect a aplicatiei TPP se trimite un cod care poate fi utilizat de aplicatia TPP pentru obtinere token de accesare a starii/datelor platii.
  7. Aplicatia TPP obtine token pentru accesarea datelor si starii platii. Pentru verificare stare plata se foloseste operatia GET /v1/{payment-service}/{payment-product}/{paymentId}/status.
  8. Serviciul bancii returneaza starea platii catre aplicatia TPP, care o afiseaza clientului.

Exemplificare flux:

1. Operatia POST /v1/{payment-service}/{payment-product} se poate utiliza cu valorile payment-service=payments si payment-product=sepa-credit-transfer , iar datele platii se trimit in format JSON. Este obligatorie transmiterea parametrilor TPP-Redirect-URI, X-IBM-Client-Id , X-Request-ID si TPP-Signature-Certificate in header-ul solicitarii.

 

 

2. In raspuns se indica starea “RCVD” (tranzactie inregistrata in vederea autorizarii), referinta platii-paymentId,  precum si linkul scaOAuth care trebuie utilizat pentru determinarea endpoint de autorizare plata, pe baza metadatelor serverului de autorizare Oauth 2.0.

3. Aplicatia TPP trebuie sa redirecteze PSU catre pagina de autentificare a bancii, utilizand endpointul de autorizare furnizat de link-ul scaOAuth.

 

Exemplul de formare a URL-ului pentru Redirect poate fi gasit in atributul “Location” al headerului raspunsului operatiei POST /v1/{payment-service}/{payment-product}:

Location :

https://api-test.cec.ro/cec/tpp/oauthcec/oauth2/authorize?

response_type=code

&scope=PIS:5d935a04-7756-11eb-a2f7-0a06001a0000

&redirect_uri=https://example.com/redirect

&client_id=286xxxxxxxxxxxxxxxxxfe8a3

&code_challenge=<code challenge value>

4. Aplicatia TPP redirecteaza clientul catre URL-ul format la pct.3, unde se deschide ecranul de autentificare client in sistemul bancii. Clientul este autentificat de banca in baza userului definit in aplicatia de Internet Banking-CECOnline si a codului de acces generat de dispozitivul fizic pe care-l detine sau de aplicatia eToken instalata pe telefonul mobil