Generate authCode via API (PSD2 flow)

General information

Some terminology

  • Person – physical ConnectPay User.
  • Customer – entity that holds accounts. It can be either Personal, either Corporate. Person can belong to several Customers of any type.
  • PSU – Payment Services User – is identified as unique Person and Customer pair.

OAuth 2.0

ConnectPay APIs are secured using OAuth2.0 model, following Authorization Code Grant flow.

To access your data via API, with each request you must present valid Access Token which is associated with Person and Customer. Your data will not be accessible to other Customers.

E.g., You, as a Person X, belong to Customer A and Customer B. You have Access Token issued to Person X and Customer A. With this Token will not be able to access Customers B data.

Getting authCode

For PSU to authorize TPP to access ConnectPay APIs, PSU should be redirected from TPP website to the ConnectPay Auth Web Application. TPP will authenticate and grant (or deny) requested data access permissions. Then PSU will be redirected back to the TPP and authCode will be added to callback URL as code query parameter. 

PSU’s access rights are stored in form of Access Token. Temporary authCode must be exchanged to Access Token in the background using server-to-server communication. 
Authorization Code will be valid for 24 hours.

To initiate authorization flow,  TPP should make GET request to the Get authCode API from User Agent application (e.g., Web browser).

Request should contain these parameters:

  • client_id – Client ID from APP created at Developer Portal.
  • flowId – to get AuthCode for exchange to Access Token, please use GetPSD2AuthCode.
  • nonce – unique GUIDv4 string, to mitigate replay attacks.
  • scope – space separated list of desired scopes. PSD2 related scopes:
    • psd2-ais – to access Account Information Services
    • psd2-pis – to access Payment Initiation Services

Note. You can not mix PSD2 and Connect Propriety scopes – request with mixed scopes will result in error response.

  • state – unique request identifier. WhenPerson will be redirected back to TPP, respose will have same state parameter – to map received authCode with Person’s ID in TPP system.
  • redirect_url – Callback URL to where Person should be redirected back after authentication and authorization. Hostname in parameter will be validated against callback URL list, provided by TPP in APP configuration at Developer Portal.

Note. Your callback URL cannot contain query parameters. There are no restrictions on path composition.

  • response_type – use code.

Sample Request

curl -X GET \
'https://api2-stage.connectpay.com/auth/v1/authorize'\
'?response_type=code' \
'&scope=psd2-ais psd2-pis' \
'&client_id=7d3069b2-0155-45c1-9600-7db93c3e5087&' \
'flowid=GetPSD2AuthCode' \
'&redirect_url=https://app.tpp.com/callback' \
'&state=w4Am91fLZMKhDMT' \
'&nonce=cd4f58e2-4af8-4b11-b2eb-894df2179fbf


ConnectPay will validate provided details and redirect User Agent to the ConnectPay Auth Web Application using http code 301 and redirect URL in location header.

Note. Redirect must NOT be implemented in HTML iFrame element. Redirect should be in full window, so the Customer could see ConnectPay URL and could validate its certificate (by clicking HTTPS lock symbol)

Authentication and Authorization

In Auth Web App, PSU will have to authenticate using SCA (Username/Password + SMS OTP/Auth Device), select desired Customer and grant/deny his data access permissions. Permissions are managed using OAuth scopes, requested by TPP in Authorize API.
 
After granting/denying access PSU will be redirected back to the TPP. If at least one requested scope was granted, callback URL will contain query parameter code with authorization Code. Use this authCode to mint Access Token. Redirect URL will also contain query parameters state and flowId:

https://app.tpp.com/callback/?code=dffa7b34-f5bc-499c-98e4-afb262563e7f&state=w4Am91fLZMKhDMT&flowId=GetPSD2AuthCode

If PSU would choose to deny all scopes (or any other error would occur on ConnectPay side), Redirect URL will not contain code, but will contain state, flowId and error parameters.

https://app.tpp.com/callback/?state=w4Am91fLZMKhDMT&flowId=GetPSD2AuthCode&error=access_denied

You can use state parameter to identify Authorize API Request and Redirect back to TPP Response pair.

Integration

DevApp creation

Scroll to Top