Quickstart: Register a user and read test transactions in the sandbox.
Each request's placeholder ({PartnerToken}, {UserToken}, ...) should be replaced with a real value
obtained from an earlier step, as described in the surrounding text. The one exception is {startDate},
which isn't returned by any step — replace it with today's date in yyyy-mm-dd format (e.g. 2026-09-09).
See Authentication for how these tokens are sent and what the API returns if one is rejected.
Create a new partner token
Use your initial partner token to create a new partner token with all required scopes and a lifetime that fits your needs — see Scopes for the full list of available scopes.
POST /partner/v2/partners/self/tokens HTTP/1.1
Host: sandbox.paydata-api.com
Authorization: Bearer {PartnerToken}
Content-Type: application/json
{
"name": "Token 1",
"expiresIn": 3600,
"scope": "partner:all user:all webhook:all"
}
{
"accessToken": "{PartnerToken}",
"id": "j2r27hmn61",
"name": "Token 1",
"createdAt": "2024-03-29T07:32:13.9396933Z",
"expiresIn": 3600,
"expiresAt": "2024-03-29T08:32:13.9396933Z",
"isRevoked": false,
"isExpired": false,
"isValid": true,
"scope": "partner:all user:all webhook:all",
"lastUsedAt": null,
"revokedAt": null
}
Your initial partner tokens have a short lifetime and will expire!
Create a new partner token with a long lifetime and at least the partner:update scope, to be able to create new tokens with updated scopes.
If all your partner tokens with the partner:update scope expire, you must contact the PayData support to obtain a new token!
Create a user
Send the following request to create your first user (replace {PartnerToken} with the token you obtained in step 1):
POST /partner/v2/users HTTP/1.1
Host: sandbox.paydata-api.com
Authorization: Bearer {PartnerToken}
Content-Type: application/json
{
"name": "my-test-user-01",
"email": "my-test-user-01@example.de"
}
{
"token": {
"accessToken": "{UserToken}",
"createdAt": "2023-06-27T11:53:14.5111120Z",
"expiresIn": 3600,
"expiresAt": "2023-06-27T12:53:14.5111120Z",
"isRevoked": false,
"isExpired": false,
"isValid": true,
"scope": "account:all transaction:all",
"lastUsedAt": null,
"revokedAt": null
},
"id": "gg61yadj21",
"name": "my-test-user-01",
"registration": "2023-06-27T11:53:12.3752185Z",
You have created the first user.
The value of the token.accessToken field ({UserToken}) is the JWT user token that you will need on the following steps. The value of the token.expiresIn field is the number of seconds the user token is valid (in our example 3600 that is one hour).
The value of the id field is the id of the user — {userId} in the following steps.
In case the token expires before you are done with this quickstart, send the following request to create a new user token (replace {PartnerToken} with the token you obtained in step 1 and {userId} with the id from the previous response):
POST /partner/v2/users/{userId}/tokens HTTP/1.1
Host: sandbox.paydata-api.com
Authorization: Bearer {PartnerToken}
Content-Type: application/json
{
"expiresIn": 3600
}
{
"accessToken": "{UserToken}",
"createdAt": "2023-06-28T08:27:41.0348938Z",
"expiresIn": 3600,
"expiresAt": "2023-06-28T09:27:41.0348938Z",
"isRevoked": false,
"isExpired": false,
"isValid": true,
"scope": "account:all transaction:all",
"lastUsedAt": null,
"revokedAt": null
}
You can use the new user token on the following steps.
Create an account
Send the following request to create an account for the user (replace {UserToken} with the user token obtained in step 2 and {startDate} with today's date in yyyy-mm-dd format):
POST /partner/v2/accounts HTTP/1.1
Host: sandbox.paydata-api.com
Authorization: Bearer {UserToken}
Content-Type: application/json
{
"accountTypeId": "dummy",
"accountFields": {
"token": "token1",
"token-secret": "secret1",
"start-date": "{startDate}T00:00:00.000",
"max-transactions-per-day": "10"
}
}
{
"id": "5dshwegr36",
"accountTypeId": "dummy",
"name": "Dummy",
"status": "Idle",
"elementStatistics": {
"count": 0,
"first": null,
"last": null
},
"accountFields": {
"generated-field": "initial-10",
"token": "token1",
"max-transactions-per-day": "10",
"start-date": "{startDate}T00:00:00.0000000Z"
}
}
You have created the first account for the user.
The value of the id field in the response is the account id — {accountId} in the following steps.
The "dummy" account type is a special account type used for testing. Transactions for accounts of that type are auto-generated beginning from start-date until today. The number of transactions per day is a random value between 1 and the value of the max-transactions-per-day field (in our example it is 10). The transactions are usually generated in a few seconds after account creation. Using today's date as start-date keeps this to a handful of transactions — an older date generates one batch per day since then, which can add up to thousands of transactions for a start date that's years in the past. Real accounts connect to an actual payment provider instead of dummy — see the list of account types for what's available.
To check if the account has transactions, send the following request (replace {UserToken} with the user token obtained in step 2 and {accountId} with the account id from the previous response):
GET /partner/v2/accounts/{accountId} HTTP/1.1
Host: sandbox.paydata-api.com
Authorization: Bearer {UserToken}
{
"id": "5dshwegr36",
"accountTypeId": "dummy",
"name": "Dummy",
"status": "Idle",
"elementStatistics": {
"count": 6,
"first": "{startDate}T00:00:00Z",
"last": "{startDate}T00:00:00Z"
},
"accountFields": {
"generated-field": "initial-10",
"token": "token1",
"max-transactions-per-day": "10",
"start-date": "{startDate}T00:00:00.0000000Z"
}
}
The elementStatistics section in the response contains the total number of transactions (count) and the dates of the earliest (first) and the latest (last) transaction.
Create an account with OAuth2 authentication
Send the following request to get a redirect URL (replace {UserToken} with the user token obtained in step 2 and {startDate} with today's date in yyyy-mm-dd format, same as in step 3):
POST /partner/v2/oauth HTTP/1.1
Host: sandbox.paydata-api.com
Authorization: Bearer {UserToken}
Content-Type: application/json
{
"accountTypeId": "dummy-oauth",
"accountFields": {
"token": "token2",
"token-secret": "secret2",
"max-transactions-per-day": "10",
"start-date": "{startDate}T00:00:00.000"
}
}
{
"redirectUrl": "{redirectUrl}",
"authReference": "{authReference}"
}
The value of the redirectUrl field is a link that redirects to the payment provider. In a real-world scenario the end user should be redirected to that link, authenticate themselves with the provider and confirm, that PayData is allowed to get transactions from that provider.
The value of the authReference field is a reference for the authentication session, that should be used further to create the account.
Navigate to the redirect URL in an Internet browser. You get the following text in the browser:
Authorization succeeded Authorization completed successfully. You can now close this window and proceed to the next step of account configuration.
This way we skip the authentication with the payment provider in our example and pretend, that the end user has just accomplished that authentication with the provider successfully.
Send the following request to create the account (replace {UserToken} with the user token obtained in step 2, {startDate} with the same date used in the previous request, and {authReference} with the reference obtained from the previous response):
POST /partner/v2/accounts HTTP/1.1
Host: sandbox.paydata-api.com
Authorization: Bearer {UserToken}
Content-Type: application/json
{
"accountTypeId": "dummy-oauth",
"accountFields": {
"token": "token2",
"token-secret": "secret2",
"start-date": "{startDate}T00:00:00.000",
"max-transactions-per-day": "10",
"auth-reference": "{authReference}"
}
}
{
"id": "xegdfke5t1",
"accountTypeId": "dummy-oauth",
"name": "Dummy OAuth",
"status": "Idle",
"elementStatistics": {
"count": 0,
"first": null,
"last": null
},
"accountFields": {
"token": "token2",
"max-transactions-per-day": "10",
"start-date": "{startDate}T00:00:00.0000000Z"
}
}
You have created another account for the user. It is a dummy account similar to step 3, refer to that step to read how transactions are created for the account.
Read test transactions
You can use any of the accounts created in steps 3 and 4 to read transactions on this step.
Send the following request to read transactions (replace {UserToken} with the user token obtained in step 2, {accountId} with the account id from step 3 or step 4, and {startDate} with the same date used as start-date in that step):
GET /partner/v2/accounts/{accountId}/transactions?order=createdAt&pageSize=2&pageNumber=1&bookingDate.start=%7BstartDate%7DT00%3A00%3A00.000&bookingDate.end=%7BstartDate%7DT00%3A00%3A00.000 HTTP/1.1
Host: sandbox.paydata-api.com
Authorization: Bearer {UserToken}
{
"transactions": [
{
"id": "ryx7hw28j6",
"bookingDate": "{startDate}T00:00:00Z",
"valueDate": "2023-06-02T00:00:00Z",
"gross": {
"currency": "USD",
"value": 682123
},
"net": {
"currency": "USD",
"value": 446714
},
"fee": {
"currency": "USD",
This requests transactions booked on a single day, {startDate} in yyyy-mm-dd format — the same date used as start-date when the account was created. To reduce the response size we get maximum 2 transactions (pageSize=2, pageNumber=1).
You have read sample transactions.
The values you get will be different, since they are randomly generated. The structure of real responses is the same, the fields section can have different fields depending on the account type.
Polling like this is fine for a quickstart, but isn't the most efficient way to stay in sync with a provider — see Staying Up to Date for using webhooks instead.