Quickstart: Register in the PayData Sandbox and read test transactions.

Examples in this quickstart use the CURL command-line tool to describe HTTP-requests and can be run using the Bash command-line interface.

Step 1. 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.

curl -L -X POST 'https://api-sandbox.paydata-api.com/partner/v2/partners/self/tokens' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {partner token}' \
--data-raw '{
  "name": "Token 1",
  "expiresIn": 3600,
  "scope": "partner:all user:all webhook:all"
}'

Response

{
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxYXg2NXhhc3c0NiIsInBhcnRuZXJJZCI6IjFheDY1eGFzdzQ2IiwianRpIjoieGEycjcxbHdwbjYxIiwic2NvcGUiOiJwYXJ0bmVyOmFsbCB1c2VyOmFsbCB3ZWJob29rOmFsbCIsIm5iZiI6MTcxMTYwNzUzMywiZXhwIjoxNzExNjExMTMzLCJpYXQiOjE3MTE2MDc1MzN9.bfiHMT31UYG5nBDvzK_VagET9Tq0NzMGKigHq01cAL8",
    "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:create",
    "lastUsedAt": null,
    "revokedAt": null
}

warning

Your initial partner tokens has 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!

Step 2. Create a user.

Send the following request to create your first user (replace the {partner token} with the token you obtained in step 1):

curl -L -X POST 'https://api-sandbox.paydata-api.com/partner/v2/users' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {partner token}' \
--data-raw '{
    "name":"my-test-user-01",
    "email": "my-test-user-01@example.de"
}'

You get a response similar to the following:

{
    "token": {
        "accessToken": "{user token}",
        "createdAt": "2023-06-27T11:53:14.511112Z",
        "expiresIn": 3600,
        "expiresAt": "2023-06-27T12:53:14.511112Z",
        "isRevoked": false,
        "isExpired": false,
        "isValid": true,
        "scope": "account:all transaction:all",
        "lastUsedAt": null,
        "revokedAt": null
    },
    "id": "{userId}",
    "name": "my-test-user-01",
    "registration": "2023-06-27T11:53:12.3752185Z",
    "lastTransfer": null,
    "lastExport": null,
    "isDeleted": false,
    "isActive": true,
    "email": "my-test-user-01@example.de"
}

You have created the first user.

The value of the "accessToken" field ({user token}) is the JWT user token that you will need on the following steps. The value of the "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 ({userId}) is the id of the user.

In case the token expires before you are done with this quickstart, send the following request to create a new user token (replace the {partner token} with the token you obtained in step 1 and {userId} with the value from the previous response):

curl -L -X POST 'https://api-sandbox.paydata-api.com/partner/v2/users/{userId}/tokens' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {partner token}' \
-d '{
    "expiresIn" : 3600
}'

You get a response similar to the following:

{
    "accessToken": "{user token}",
    "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.

Step 3. Create an account.

Send the following request to create an account for the user (replace the {user token} with the user token obtained in step 2):

curl -L -X POST 'https://api-sandbox.paydata-api.com/partner/v2/accounts' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {user token}' \
-d '{
  "accountTypeId": "dummy",
  "accountFields":
  {
    "token": "token1",
    "token-secret": "secret1",
    "start-date": "2023-06-01T00:00:00.000",
    "max-transactions-per-day": "10"
  }
}'

You get a response similar to the following:

{
    "id": "{accountId}",
    "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": "2023-06-01T00:00:00.0000000Z"
    }
}

You have created the first account for the user.

The value of the "id" field {accountId} is the account id, you will need this value on 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.

To check if the account has transactions, send the following request (replace the {user token} with the user token obtained in step 2 and {accountId} with the account id from the previous response):

curl -L -X GET 'https://api-sandbox.paydata-api.com/partner/v2/accounts/{accountId}' \
-H 'Authorization: Bearer {user token}'

You get a response similar to the following:

{
    "id": "{accountId}",
    "accountTypeId": "dummy",
    "name": "Dummy",
    "status": "Idle",
    "elementStatistics": {
        "count": 187,
        "first": "2023-06-01T00:00:00Z",
        "last": "2023-06-27T00:00:00Z"
    },
    "accountFields": {
        "generated-field": "initial-10",
        "token": "token1",
        "max-transactions-per-day": "10",
        "start-date": "2023-06-01T00: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.

Step 4. Create an account with OAuth2 authentication.

Send the following request to get a redirect URL (replace the {user token} with the user token obtained in step 2):

curl -L -X POST 'https://api-sandbox.paydata-api.com/partner/v2/oauth' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {user token}' \
-d '{
  "accountTypeId": "dummy-oauth",
  "accountFields":
  {
    "token": "token2",
    "token-secret": "secret2",
    "max-transactions-per-day": "10",
    "start-date": "2023-06-01T00:00:00.000"
  }
}'

You get a response similar to the following:

{
    "redirectUrl": "{redirectUrl}",
    "authReference": "{authReference}"
}

The value of the "redirectUrl" field ({redirectUrl}) is a link that redirects to the payment provider. In a real-world scenario the 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 ({authReference}) is a reference for the authentication session, that should be used further to create the account.

Navigate to the redirect URL ({redirectUrl}) 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 user has just accomplished that authentication with the provider successfully.

Send the following request to create the account (replace the {user token} with the user token obtained in step 2 and {authReference} with the reference, obtained from the previous response):

curl -L -X POST 'https://api-sandbox.paydata-api.com/partner/v2/accounts/' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {user token}' \
-d '{
  "accountTypeId": "dummy-oauth",
  "accountFields":
  {
    "token": "token2",
    "token-secret": "secret2",
    "start-date": "2023-06-01T00:00:00.000",
    "max-transactions-per-day": "10",
    "auth-reference":"{authReference}"
  }
}'

You get a response similar to the following:

{
    "id": "{accountId}",
    "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": "2023-06-01T00: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.

Step 5. 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 the {user token} with the user token obtained in step 2 and {accountId} with the account id from step 3 or from step 4):

curl -L -X GET 'https://api-sandbox.paydata-api.com/partner/v2/transactions?Order=createdAt&PageSize=2&PageNumber=1&AccountId={accountId}&start=2023-06-01T00%3A00%3A00.000&end=2023-06-01T00%3A00%3A00.000' \
-H 'Authorization: Bearer {user token}'

This is a request to get transactions from 01.06.23 to 01.06.23 (we used this value in steps 3 and 4 as "start-date"). To reduce the response size we get maximum 2 transactions (PageSize=2, PageNumber=1).

You get a response similar to the following:

{
    "transactions": [
        {
            "id": "ryx7hw28j6",
            "bookingDate": "2023-06-01T00:00:00Z",
            "valueDate": "2023-06-02T00:00:00Z",
            "gross": {
                "currency": "USD",
                "value": 682123
            },
            "net": {
                "currency": "USD",
                "value": 446714
            },
            "fee": {
                "currency": "USD",
                "value": -235409
            },
            "isBalanceRelevant": true,
            "paymentClassification": "Payment",
            "transactionId": "TR 53205462-bd02-466f-ab47-202e04008558 123",
            "orderNumber": "ORD 10127 123",
            "receiptNumber": "INV 94386 123",
            "bookingText": "Test transaction 61535 123",
            "createdAt": "2023-06-27T11:55:20.6195126Z",
            "lastModifiedAt": "2023-06-27T11:55:20.6195473Z",
            "report": null,
            "fields": {
                "payerName1": "Rico Moen 123",
                "payerName2": "jeramie.pouros@rosenbaum.us 123",
                "invoiceNumber": "INV 94386 123",
                "orderNumber": "ORD 10127 123",
                "transactionId": "TR 53205462-bd02-466f-ab47-202e04008558 123",
                "reference1": "Ref1 02864 123",
                "reference2": "Ref2 24803 123",
                "reference3": "Ref3 Dolor eos qui doloru 123",
                "reference4": "Ref4 Accusamus error et v 123",
                "bookingText": "Test transaction 61535 123",
                "paymentType": "payout"
            }
        },
        {
            "id": "67xvh5yn1r",
            "bookingDate": "2023-06-01T00:00:00Z",
            "valueDate": "2023-05-29T00:00:00Z",
            "gross": {
                "currency": "CHF",
                "value": 13614
            },
            "net": {
                "currency": "CHF",
                "value": 13503
            },
            "fee": {
                "currency": "CHF",
                "value": -111
            },
            "isBalanceRelevant": true,
            "paymentClassification": "Payment",
            "transactionId": "TR df6d9d72-686d-4fe5-ae42-5588b70316f6 123",
            "orderNumber": "ORD 30723 123",
            "receiptNumber": "INV 79378 123",
            "bookingText": "Test transaction 85874 123",
            "createdAt": "2023-06-27T11:55:20.6238604Z",
            "lastModifiedAt": "2023-06-27T11:55:20.6238605Z",
            "report": null,
            "fields": {
                "payerName1": "Pearline Stiedemann DVM 123",
                "payerName2": "kaylie_littel@weimanntorp.ca 123",
                "invoiceNumber": "INV 79378 123",
                "orderNumber": "ORD 30723 123",
                "transactionId": "TR df6d9d72-686d-4fe5-ae42-5588b70316f6 123",
                "reference1": "Ref1 88647 123",
                "reference2": "Ref2 55630 123",
                "reference3": "Ref3 Voluptatem quaerat e 123",
                "reference4": "Ref4 Modi alias accusamus 123",
                "bookingText": "Test transaction 85874 123",
                "paymentType": "payout"
            }
        }
    ],
    "pagination": {
        "pageNumber": 1,
        "pageSize": 2,
        "pagesCount": 3,
        "totalCount": 6
    }
}

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.

Step 1. Create a new partner token​

Step 2. Create a user.​

Step 3. Create an account.​

Step 4. Create an account with OAuth2 authentication.​

Step 5. Read test transactions.​

Step 1. Create a new partner token

Step 2. Create a user.

Step 3. Create an account.

Step 4. Create an account with OAuth2 authentication.

Step 5. Read test transactions.