Accounts

An account in PayData represents a connection including the necessary credentials to one of the external systems or PSPs. This connection is used to fetch transactions from the external system or PSP.

After a user has been created and has obtained a JWT token, the partner software on behalf of the user can create, update and delete accounts.

• The CreateAccount method is used to create an account. For accounts with OAuth2 authentication it is necessary to additionally use the CreateOauthRedirectUrl method first.
• The UpdateAccount method is used to update an account. To update the connection settings for accounts with OAuth2 authentication it is necessary to additionally use the CreateAccountOauthRedirectUrl method first.
• The DeleteAccount method is used to delete an account, if it is no more required.

To view user accounts in the partner software partners can use

• the GetAccounts method to get a list of user accounts;
• the GetAccount method to get detailed user account information.

Before creating an account, it is necessary to select an account type. The account type determines

• the payment provider;
• the authentication schema;
• the required and optional parameters.

Create an account

Account creation must be authorized using a user token (see User Management). Check the available Account Types for your partner and use the ID of the desired type. The account types use different authentication mechanisms and therefore the different information is needed upon account creation. All required Account Fields must be present, when creating an account.

POST https://api-sandbox.paydata-api.com/partner/v2/accounts
Authorization: Bearer {UserToken}
Content-Type: application/json

{
    "accountTypeId": "dummy",
    // "name": "MyName", // optional,
    "accountFields": {
        "start-date": "2023-08-10T22:00:00", // UTC
        "token": "Username",
        "token-secret": "Password"
    }
}

The response should look like this.

{
    "id": "82j1hyaehz",
    "accountTypeId": "dummy",
    "name": "Dummy",
    "status": "Idle",
    "elementStatistics": {
        "count": 0,
        "first": null,
        "last": null
    },
    "accountFields": {
        "generated-field": "initial-",
        "token": "Username",
        "max-transactions-per-day": null,
        "start-date": "2023-08-10T22:00:00.0000000Z"
    }
}

Creating an account with OAuth2 authentication

If the response from the GetAccountType method contains an element in the accountFields array with Type = Auth, then the account of that type uses OAuth2 authentication to connect to the payment provider.

In that case the account is created as follows:

First, the CreateOauthRedirectUrl method is called by the partner software, the response from the PayData API contains

• a redirect URL for the provider: redirectUrl;
• an authentication reference to create the account: authReference

Second, the user must be redirected to the redirectUrl, obtained on the first step. Optionally a new browser window can be opened. When the authorization completes the user is redirected back to the PayData API with the result.

If the partner has an OAuth2 redirect URL, the PayData API redirects the user to this URL with the result passed in the following query parameters:

• reference - the authentication reference authReference, that was obtained on the first step of the process
• status - the authentication process status code that can be Success, NotFoundError, OtherError
• message - a message describing the result that should be displayed to the user

If the status code is Success, the partner software can proceed to the next step without user action. Otherwise action should be taken to fix the error and try again.

If the partner doesn't have an OAuth2 redirect URL, the user is redirected to a simple page with either a successful result or an error message. The partner software should allow the user to initiate the next step manually.

In any case the HTTP response headers contain the following information:

• X-PayJoe-AuthReference - the authentication reference authReference, that was obtained on the first step of the process
• X-PayJoe-AuthStatus - the authentication process status code that can be Success, NotFoundError, OtherError
• X-PayJoe-AuthMessage - a message describing the result

Third, the CreateAccount method is called by the partner software with the authentication reference authReference, that was obtained on the first step of the process.