Credentials and Authorization

PayData accounts need credentials to access data of your enduser. These credentials must be provided when creating an account and depend on the type of the account. See Account Fields and the list of account types on how to obtain the fields required to create an account.

Usually these credentials take the form of

• a username and password,
• an API token or
• an access token obtained using an OAuth flow.

Additionally information such as an start date, API endpoint or shop name might also be necessary.

Username and Password

The following example shows how to create an Adyen account that requires a start date, username, password and a merchant account name using the create account endpoint.

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

{
    "accountTypeId": "adyen",
    "accountFields": {
        "start-date": "2023-08-10T22:00:00",
        "username": "Username",
        "password": "Secret",
        "merchant-account-name": "AdyenMerchantName"
    }
}

Updating credentials

The credentials can be updated in the same way using the update account endpoint.

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

{
    "accountFields": {
        "password": "Secret"
    }
}

OAuth Authorization

Creating accounts that require an authorization through OAuth require that an redirect URI is requested from PayData where the user must redirected to. If the required fields for an account type contain a field of Type = Auth, then an account of that type uses OAuth to connect to the PSP.

The following sequence diagram shows the required steps.

1. A user wants to create a new account and clicks a button in the Partner software.
2. The create an OAuth Redirect URL endpoint is called by the partner software.
   • An accountTypeId must be specified.
   • Depending on the account type, additional accountFields must be passed.
   • An optional redirectUrl can be specified where the user is redirected in step 13. The URL must be whitelisted in the partner settings.
3. The response from the PayData API contains
   • a redirect URL for the provider: redirectUrl
   • an authentication reference to create the account: authReference
4. The parnter software sends the redirect URL to the user.
5. The user opens the URL in a web browser and
6. is redirected to the PSP that
7. shows an login and/or authorization page that shows that PayData wants to access transactions, payouts, ...
8. The user accepts the authorization and
9. the PSP processes/validates the response after which
10. the PSP returns a PayData URL that processes the autorization and
11. the user is redirected to it.
12. PayData requests the access tokens from the PSP,
13. which the PSP happily returns. The tokens are stored temporarily.
14. Paydata returns the redirect URI specified in step 2 or to the default URL for the partner.
15. The User is redirected to the URL. The partner can then process the authorization response and
16. Create account method is called by the partner software with the auth-reference in accountFields.
17. On successfull creation of the account PayData returns the account.
18. The User is then redirected to a final status page that displays the result.

The redirect URL in step 15 contains the following query parameters and headers.

Query	Header	Description
reference	X-PayJoe-AuthReference	The authentication reference authReference, that was obtained on the first step of the process
status	X-PayJoe-AuthStatus	The authentication process status code that can be Success, NotFoundError, OtherErrorprocess
message	X-PayJoe-AuthMessage	A message describing the result

Refreshing the Authorization

Validation

When an account is created the credentials are validated by making an connection to the PSP. If the validation fails, the API responds with an 412 Precondition Failed status code and the account is not created or updated. This can be ignored by setting ignoreTestErrors true when creating or updating an account. This can be useful if the credentials are known to be correct but a problem exists elsewhere (PSP or PayData).

It is also possible to validate the credentials before creating or updating an account with the validate account type credentials and validate account credentials endpoints.

Example: Adyen account type credentials validation

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

{
  "username": "Username",
  "password": "Secret",
  "merchant-account-name": "AdyenMerchantName"
}