Account UI

Accounts in PayData can be created and updated using the Account UI - a graphical user interface that enables end-users to interactively select an account type and specify required account settings and credentials. For accounts with OAuth2 authentication Account UI redirects the user to a web site of the payment provider where the user logs in and authorizes PayData to read transactions.

Overview

To create or update an account with the Account UI, the partner software should follow these steps:

1. Initiate a session by calling the Create Account UI endpoint that a new session and returns its URL.
2. Open the Account UI session URL for the end user who interacts with Account UI and enters the necessary data.
3. Get the status of the session and if it ended successfully, get the ID of the created account, save and use it later to get transactions.

If you specify a redirect URL in step 1, the Account UI redirects to that URL when the session is completed and returns the resulting status of the session and the ID of the created account if the session succeeds.

If you do not specify a redirect URL in step 1, Account UI displays a window with results at the end of the session. The user should close the window and then you can call the PayData API endpoint that returns the status of a UI session. The results for a successful session contain the ID of the created account.

Details for these steps are provided below.

Add a redirect URL

If you have one or several URLs that can be redirected to after the Account UI session is completed, specify these in the partner settings. Then you can use one of these URLs in step 1 to facilitate smooth transfer of control from Account UI to partner software at the end of the Account UI session.

Use the UpdatePartner endpoint to set up redirect URLs as in this example:

curl -L -X PUT 'https://api-sandbox.paydata-api.com/partner/v2/partners/self' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {Token}' \
--data-raw '{
  "email": "partner@example.de",
  "name": "First Partner",
  "redirectUrls": [
    "https://example.de/oauth_redirect_url1",
    "https://example.de/oauth_redirect_url2"
  ],
  "userTokenExpirySeconds": 3600,
  "uiSettings": {
    "redirectUrls": [
      "https://example.de/ui_redirect_url1",
      "https://example.de/ui_redirect_url2"
    ]
  }
}'

• Replace {Token} with the JWT token of the partner
• Specify redirect URLs in the uiSettings.redirectUrls array
• See UpdatePartner for a description of other parameters

Step 1. Create a UI session.

To initiate a Account UI session use the CreateAccountUi endpoint as in this example:

curl -L -X POST 'https://api-sandbox.paydata-api.com/partner/v2/accountui' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {Token}' \
--data-raw '{
  "expiresIn": 3600,
  "accountId": "5dshwegr36",
  "accountTypeIds": [ "dummy-oauth" ],
  "redirectUrl": "https://example.de/ui_redirect_url"

• Replace {Token} with the JWT token of the user who creates the account
• Specify accountId when updating an existing account
• Provide accountTypeIds when you want to restrict the available types. If more than one account type is available, the user selects the account type in Account UI in step 2.1.
• Set expiresIn in seconds to determine how long the link to the session remains valid. Default value is 3600 seconds..
• Add your redirectUrl to be redirected to after the Account UI session is completed. If specified, it should be whitelisted in the partner's settings.

You get a response similar to the following:

{
  "url": "https://api-sandbox.paydata-api.com/partner-ui/v1/g3hzuek4c17",
  "id": "g3hzuek4c17",
  "expiresIn": 3600,
  "createdAt": "2023-12-12T13:19:32.9709497Z",
  "expiresAt": "2023-12-12T14:19:32.9709497Z",
  "accountTypeIds": [ "dummy-oauth" ]
}

• url is the URL where the user should be redirected
• id is the session id which can be used to get the session status with GetAccountUiStatus
• expiresIn is how long the link to the session remains valid in seconds
• createdAt is the timestamp of the session creation
• expiresAt is the timestamp of the expiration of the url
• accountId is returned only if specified in the request when updating an existing account

Step 2. Use Account UI

Redirect the user to the URL obtained in step 1. Now the Account UI session starts.

At this step the user interacts with Account UI to choose an account type and to enter settings and credentials authorizing PayData to get data from the selected payment provider.

2.1. Choose account type

If a new account is being created (accountId was not specified), the Account UI presents a list of available account types. From these, the user selects the account type to be created. If only a single type is available, the Account UI proceeds directly to step 2.2.

2.2. Enter account settings and credentials

Once the desired account type is chosen, a form is opened to fill out settings and credentials required for that particular account type. Before proceeding to the next step, a connection test is automatically performed in the background to validate the credentials.

2.3. Authenticate with payment provider

For some account types it is necessary to additionally authenticate with the respective provider. If that is the case, the user is redirected the the provider's web site where he or she enters credentials for that provider and authorizes PayData to obtain transactions.

Afterwards the user is automatically redirected back to Account UI.

Step 3. Get session status and account id

Now the Account UI session is completed.

If no redirectUrl was provided in step 1, the user gets a confirmation message on the screen that the account has been successfully created or updated.

In case an error occurred, the user receives an error message instead.

At this point to obtain the status of the completed session and the id of the created account call the GetAccountUiStatus endpoint as in this example:

curl --location 'https://api-sandbox.paydata-api.com/partner/v2/accountui/{SessionId}' \
  --header 'Authorization: Bearer {Token}'

• Replace {Token}with the JWT token of the user
• Replace {SessionId} with id from step 1, in the example above it is g3hzuek4c17

You get a response similar to the following:

{
    "status": "Success",
    "id": "7jhmfwjame",
    "expiresIn": 3600,
    "createdAt": "2024-03-27T10:07:21.4085368Z",
    "expiresAt": "2024-03-27T11:07:21.4085368Z",
    "accountId": "xegdfke5t1",
    "accountTypeIds": [ "dummy-oauth" ]
}

• status can be Success, Canceled, Error or Expired. If Success, accountId can be used to get transactions
• accountId is the id of the created or updated account
• accountTypeId is the account type that was initially requested in step 1

If a redirect URL was specified in step 1, then instead of showing a message, Account UI redirects the user to that URL and provides results of the session in query parameters as in this example:

https://example.de/some_redirect_url?sessionId=7jhmfwjame&status=Success&message=Account%20created%20successfully&accountId=xegdfke5t1

• sessionId is the session id from the response on step 1
• status can be Success, Error or Canceled
• message is a text message in case of an error
• accountId is the account id to be used to get transactions