Skip to main content

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. name is optional.

POST /accounts
CreateAccount
POST /partner/v2/accounts HTTP/1.1
Host: sandbox.paydata-api.com
Authorization: Bearer {UserToken}
Content-Type: application/json
Request Body
{
  "accountTypeId": "dummy",
  "accountFields": {
    "start-date": "2023-08-10T22:00:00",
    "token": "Username",
    "token-secret": "Password"
  }
}
Response — HTTP/1.1 200
{
  "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.

See OAuth Authorization for the full flow — requesting a redirect URL, sending the user to the PSP, and handling the result — then call CreateAccount with the resulting authReference to finish creating the account.

Status​

The status field on an account can be one of:

  • Idle - the account is not currently being fetched from; this is also the state a healthy account sits in between fetches.
  • Updating / PreparingUpdate - PayData is currently fetching data for the account.
  • ErrorCredentialsFailed / ErrorCredentialsMissing - the account's credentials are invalid or missing; see Credentials and Authorization.
  • OtherError - a failure that doesn't fall into the categories above; check the account's errors array for details — see Errors and Warnings for the format.
note

status alone isn't a reliable way to detect "still fetching" for every connector — see Staying Up to Date for why, and for the recommended way to track new data without polling status at all.