Skip to main content
Version: 2.7.1

PayData API

Guide

This API allows partners to access transactions from various payment providers.

Definition of terms​

PayData API​

PayData API is a cloud service with a suite of interfaces to various payment providers, such as Amazon, PayPal, Klarna etc. The interface portfolio of PayData offers a uniform access to detailed transactions data from all the connected providers without the need to implement a separate interface for each provider.

Partner​

The developers of a software and/or the software development company that integrates this API.

Partner software​

A software system that uses PayData API functionality to get transactions from connected payment providers.

User​

A company or a person using the partner software. Each user must be registered by the partner and has its own set of accounts.

Account​

Settings and credentials, required to connect to a payment provider and authorize the user with that provider. After creating an account the user can read transactions from the payment provider. Each provider requires its own separate account to be created for each user.

Account type​

Determines, to which payment provider to connect and describes settings and credentials required to make the connection.

OAuth2 redirect URL​

A URL provided by the partner where the user is redirected to by the PayData API after a successful completion of the OAuth2 authentication process. Its purpose is to notify the partner software, that the OAuth2 authentication either completed successfully and account can be created or that an error has occurred.

PayData allows to specify multiple OAuth2 redirect URLs in the partner's settings. One of these can be specified when the process of account creation with OAuth2 authentication is initiated (see "Creating an account with OAuth2 authentication"). If no redirect URL for the process is specified, the first one from the partner's settings is used by default. If the partner has no redirect URLs, the user is redirected to a simple page with with either a successful result or an error message after the account creation process is completed.

Transaction​

Information about an operation such as payment, refund or fee conducted through the payment provider.

Administering partner settings​

Partners should contact support (support@paydata-api.com) to get registered and obtain a JWT token. The token should be kept secret from the users as it allows to perform administrative tasks.

Without extra permissions partners can then change some of their settings, such as

  • Email address;
  • One or multiple OAuth2 redirect URLs;

through

Depending on permissions partners may be able to create and revoke JWT access tokens, create other "child" partners and change their settings.

through

The use of these methods is optional, since all the settings can be adjusted through the support team upon request.

Creating and managing users​

A user should be registered and get a JWT token. The token allows the user to create accounts and read transactions. Users have access only to their own accounts that they themselves have created.

To create accounts and get user tokens, the partner software uses:

  • CreateUser method to create a user and get the first user token;
  • CreateUserToken method to get a new token at a later point in time when the previous token is expired or about to expire.

Additionally, to view user information or get statistics, partners can use

  • GetUsers method to get a list of users;
  • GetUser method to get detailed info about a user.

To delete a user partners can use

Creating and managing accounts​

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.

Selecting an account type​

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.

To get information about account types, partners can use

  • the GetAccountTypes method, to get a list of all available account types;
  • the GetAccountType method, to get detailed info about the parameters, required to create the account. It is recommended to use the accountFields array of the metadata returned by this method to dynamically build the user interface for the selected account type. Each account type should not be hard-coded.

Dummy account types​

For development and testing purposes, the PayData API provides a set of so-called dummy account types. These can be used to test the partner software without connecting to a real payment provider.

  • the GetAccountTypes method returns dummy types along with the real ones;
  • the details of each type can be obtained with the GetAccountType method

There are the following dummy account types:

  • dummy - type without OAuth2 authorization and without reports;
  • dummy-auth - type with OAuth2 authorization;
  • dummy-report - type with reports;

The dummy account types are available in the sandbox environment only.

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. If the partner has a redirect URL where the user should be redirected to after the OAuth2 authentication process is completed, it can be specified as a parameter for the call. If no redirect URL is specified, the first one from the partner's settings is used by default. If no redirect URLs are specified in the partner's settings, the user is redirected to a simple page with either a successful result or an error message after the account creation process is completed.

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.

Reading transactions​

After an account is created, PayData starts fetching transactions from the payment provider. Depending on the account type and the amount of transactions, this process can take from a couple of seconds up to hours.

Once transactions are available for the account they can be obtained with

  • the GetTransactions method. The method returns all transactions, that have been downloaded from the payment provider.

Before calling the GetTransactions method it is useful to call the GetAccount method to determine whether there are any new transactions available. It returns the elementStatistics object with

  • the number of transactions: count;
  • the date of the first transaction: first;
  • and the date of the last transaction: last for the account.

In some cases, it can be necessary to re-read transactions from a payment provider for a particular period of time. It can be done with

  • the TriggerAccountRefresh method. The method tells PayData to re-read transactions from a payment provider, starting from the specified date.

Changelog

Version 2.7.1 (11.12.2024)

  • Add state, errors and warnings to the response model of GetAccountType endpoint to provide information about current PSP status.

Version 2.7.0 (05.11.2024)

  • New classification Tax (e.g. sales taxes).

  • New classification Adjustment for miscellaneous adjustments (e.g. rounding errors).

  • Add Shopper with information about the shopper to the response of GetTransactions and GetTransaction.

  • Add excludeDeprecatedFields as a parameter to GetTransactions and GetTransaction.
    Setting this parameter to true will exclude the transaction fields that are marked as deprecated from the list of fields.

  • Add excludeMappedFields as a parameter to GetTransactions and GetTransaction.
    Setting this parameter to true will exclude the transaction fields that are mapped to one of the fixed transaction fields such as orderNumber or bookingText.

  • Add errors and warnings to the response models of account, report and data import in GetAccount, GetAccounts, GetReport, GetReports, GetDataImport and GetDataImports.

  • Add errors to the response model of account in CreateAccount and UpdateAccount.

Version 2.6.1 (26.09.2024)

  • Ensure date-time values always have the same number of fractional seconds. Previously zeros were truncated but the full available resolution of the timestamp was provided.

    BeforeAfter
    2024-06-16T06:01:29Z2024-06-16T06:01:29.0000000Z
    2024-09-25T07:51:06.352486Z2024-09-25T07:51:06.3524860Z

Version 2.6.0 (26.08.2024)

Version 2.5.0 (25.07.2024)

  • Changed endpoints:

    • The list of transactionFields of the account type metadata now contains isDeprecated and deprecationReason properties to indicate that a field should not be used anymore.
    • The change partner's own settings endpoint now contains a new uiSettings.styling property to allow customization of the Account UI. See the styling documentation for details.
    • Add name, email and search as parameters to GetUsers

  • Metadata updates for most account types (see 2024-07 Metadata Updates)

    • New, more descriptive fields IDs and names (e.g. payoutId instead of reference1).
    • Deprecation of old field names.
    • Removal of 'bookingDate' and 'valueDate' from the transaction fields as the values only duplicated information from the main transaction.
    • Removal of fields that were never used by a PSP.
    • Removal of fields with dubious data quality.

Version 2.4.0 (01.07.2024)

  • Changed endpoints:
    • All changes are backwards compatible. However, there are deprecations that will be removed in the future. The new API offers more flexibility and features.
    • POST /accountui:
      • Add accountTypeIds as request / response body parameter
      • Deprecate accountTypeId as request / response body parameter - use accountTypeIds instead
      • See create or update an account
    • GET /accountui/{id}:

Version 2.3.0 (22.04.2024)

Version 2.2.2 (05.03.2024)

Version 2.2.1 (29.02.2024)

Version 2.1.6 (11.01.2024)

Version 2.1.5 (21.11.2023)

  • Add deletedAt to deleted users in GetUsers

Version 2.1.4 (09.10.2023)

  • Add user update method
  • Allow changing child partner's name in the partner update method

Version 2.1.3 (12.05.2023)

Version 2.1.2 (02.05.2023)

  • Add child partner delete methods

Version 2.1.1 (27.04.2023)

  • Add partner token revocation and usage timestamps

Version 2.1.0 (24.04.2023)

  • Add account credentials validation methods

Version 2.0.0-beta3 (31.03.2023)

  • Add rate limiting

Version 2.0.0-beta2 (23.02.2023)

  • The redirectUrl prorerty has been added to the POST /oauth request model, which allows to specify the redirect URL for any particular request.
  • Breaking changes
    • Partner request and response models have been changed. The redirectUrl prorerty has been removed and the redirectUrls prorerty has been added instead, which allows to specify multiple redirect URLs.

Version 2.0.0-beta1 (17.02.2023)

  • Add partner tokens and allow partners to add other partners.
  • Add scopes to partner and user tokens.
  • New endpoints
    • POST /partners
    • GET /partners/self
    • PUT /partners/self
    • GET /partners/{id}
    • PUT /partners/{id}
    • POST /partners/{id}/tokens
    • POST /partners/self/tokens
    • DELETE /partners/{id}/tokens/{tokenId}
    • GET /partners/self/tokens
    • GET /partners/{id}/tokens
    • POST /users/{id}/tokens. Replaces GET /users/{id}/token.
    • GET /users/{id}. Replaces GET /users/{name}. A user token and a user ID are added to the response model. An optional Email parameter is added to the response model.
  • Endpoints with extended request or response models, non-breaking changes
    • POST /users. A user token and a user ID are added to the response model. An optional Email parameter is added to both request and response models.
  • Breaking changes
    • Partner authentication with API-keys has been removed. JWT bearer tokens should be used instead. All partner keys must be replaced with the tokens.
    • Transaction CreationTimestamp was renamed to CreatedAt
    • All user tokens should be updated to contain scopes. For that the POST /users/{id}/tokens endpoint can be used.
    • The following endpoints have been removed
      • GET /users/{id}/token. POST /users/{id}/token should be used instead. The response model has changed.
      • PATCH /partners. PUT /partners/self should be used instead.
    • The following endpoints have been changed
      • GET /partners. GET /partners/self should be used instead.
      • GET /users/{name}. GET /users/{id} should be used instead.
      • DELETE /users/{name}. GET /users/{id} should be used instead.

Version 1.1.2

  • Make user token expiry configurable.

Version 1.1.1

  • Internal bug fix release.

Version 1.1.0

  • Add report information to transactions.

Version 1.0.0

  • Initial version.

Rate limiting

The following global rate limiting policies apply to all requests, sent to the API from a partner or from a user:

Period (seconds)Maximum number of requests
60100

Additional rate limiting policies may apply to some methods and are described for each particular method.

Authentication​

Security Scheme Type:

http

HTTP Authorization Scheme:

bearer

Bearer format:

JWT