Generate authCode via API (PSD2 flow)

You need an online banking account and a developer app to generate an authorization code (authCode) via the ConnectPay Online Banking Portal.

Terminology:

  • Person: A physical ConnectPay User.
  • Customer: An entity that holds accounts, either Personal or Corporate. A Person can belong to several Customers of any type.
  • PSU (Payment Services User): Identified as a unique Person and Customer pair.

OAuth 2.0

ConnectPay APIs are secured using the OAuth 2.0 model, following the Authorization Code Grant flow. To access your data via API, each request must present a valid Access Token associated with a 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

  1. Initiate Authorization:
    • Redirect the PSU from the TPP website to the ConnectPay Auth Web Application.
    • The PSU will authenticate and grant (or deny) permission to access the requested data.
    • The PSU will be redirected back to the TPP, and the authCode will be added to the callback URL as a code query parameter.
  2. Exchange authCode:
    • The temporary authCode must be exchanged for an Access Token using server-to-server communication.
    • The Authorization Code is valid for 24 hours.
  3. API Request:
    • Make a GET request to the Get authCode API from the User Agent application (e.g., Web browser).
    • Include parameters such as client_id, flowId, nonce, scope, state, redirect_url, and response_type.

Request 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
  • state – a unique request identifier. When the Person is redirected back to TPP, the response will have the same state parameter—to map the received authCode with the Person’s ID in the TPP system.
  • redirect_url – the callback URL to where the Person should be redirected after authentication and authorization. The hostname in this parameter will be validated against the callback URL list provided by TPP in the APP configuration at the Developer Portal.
  • 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'

API rules

  • You can not mix PSD2 and Connect Propriety scopes – a request with mixed scopes will result in the error response.
  • Your callback URL cannot contain query parameters. There are no restrictions on path composition.
  • Redirect must NOT be implemented in the HTML iFrame element. Redirect should be in full window so the Customer can see ConnectPay URL and validate its certificate (by clicking the HTTPS lock symbol)
  • ConnectPay will validate the provided details and redirect the User Agent to the ConnectPay Auth Web Application using HTTP code 301 and the redirect URL in the location header.

Authentication and Authorization

  • Authentication: The PSU will authenticate using SCA (Username/Password + SMS OTP/Auth Device), select the desired Customer, and grant/deny data access permissions.
  • Authorization: Permissions are managed using OAuth scopes requested by the TPP in the Authorize API.
  • Redirection: After granting/denying access, the PSU will be redirected back to the TPP. If at least one requested scope was granted, the callback URL will contain a query parameter code with an 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
  • Denied flow: If PSU chooses to deny all scopes (or any other error occurs on ConnectPay’s side), the Redirect URL will not contain code but state, flowId, and error parameters.
    • https://app.tpp.com/callback/?state=w4Am91fLZMKhDMT&flowId=GetPSD2AuthCode&error=access_denied
  • You can use the state parameter to identify Authorize API Request and Redirect back to the TPP Response pair.

For more detailed instructions, refer to the product-related documentation.

Feel free to let me know if you need any further adjustments!

API Access

Integration Security

Scroll to Top