Credentials and Authorization

PayData accounts need credentials to access data of your end user. 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 a 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 /accounts

CreateAccount

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

Request Body

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

Response — HTTP/1.1 200

{
  "id": "5dshw36",
  "accountTypeId": "adyen",
  "name": null,
  "status": "Idle",
  "elementStatistics": {
    "count": 0,
    "first": null,
    "last": null
  },
  "accountFields": {
    "start-date": "2023-08-10T22:00:00.0000000Z",
    "username": "Username",
    "merchant-account-name": "AdyenMerchantName"
  }
}

Updating credentials

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

PUT /accounts/5dshw36

UpdateAccount

PUT /partner/v2/accounts/5dshw36 HTTP/1.1
Host: sandbox.paydata-api.com
Authorization: Bearer {UserToken}
Content-Type: application/json

Request Body

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

Response — HTTP/1.1 200

{
  "id": "5dshw36",
  "accountTypeId": "adyen",
  "name": null,
  "status": "Idle",
  "elementStatistics": {
    "count": 0,
    "first": null,
    "last": null
  },
  "accountFields": {
    "start-date": "2023-08-10T22:00:00.0000000Z",
    "username": "Username",
    "merchant-account-name": "AdyenMerchantName"
  }
}

OAuth Authorization

Creating accounts that require an authorization through OAuth require that a redirect URI is requested from PayData where the end user must be 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. An end 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 end user is redirected in step 13. The URL must be whitelisted in the partner's redirectUrls setting — see the troubleshooting note below if you get a 400 Invalid redirect URL error.
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 partner software sends the redirect URL to the end user.
5. The end 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 end user accepts the authorization and
9. the PSP processes/validates the response after which
10. the PSP returns a PayData URL that processes the authorization and
11. the end user is redirected to it.
12. PayData requests the access tokens from the PSP,
13. which the PSP 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 end 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 successful creation of the account PayData returns the account.
18. The end user is then redirected to a final status page that displays the result.

Troubleshooting: "Invalid redirect URL"

If create an OAuth Redirect URL responds with 400 Bad Request: Invalid redirect URL '<your URL>', the redirectUrl you passed does not exactly match one of the URLs registered in the partner's redirectUrls (see Settings) — matching is on the full URL (scheme, host, port, and path).

POST /partner/v2/oauth with an unregistered redirectUrl

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid redirect URL 'http://localhost:5174/oauth-callback'"
}

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, OtherError
message	X-PayJoe-AuthMessage	A message describing the result

Collecting fields alongside OAuth

An OAuth account type (one with a field of Type = Auth) can still have other required fields — for example dummy-oauth also requires token and token-secret alongside its auth-reference. Each such field's requiredDuringAuth flag (see Account Fields) tells you when it needs to be supplied:

• Fields with requiredDuringAuth: true must be included in accountFields when calling CreateOauthRedirectUrl, before the end user is sent to the PSP. PayData carries these values through to the final CreateAccount call automatically, so you don't need to resupply them there.
• Fields with requiredDuringAuth: false (the default) may instead be collected afterwards, and passed for the first time in the final CreateAccount call's accountFields, alongside auth-reference.

Both approaches are valid — pick whichever fits your UI flow better: ask for everything up front, or only ask for the OAuth-independent fields once the end user is back from the PSP.

Required fields are only checked for presence, not for a non-empty value

Don't assume the API will always catch a required field the end user left blank as opposed to not supplied at all — client-side validation of required fields (present and non-empty) is recommended before calling CreateOauthRedirectUrl or CreateAccount, rather than relying solely on the API to reject an empty value. This is easy to get wrong specifically for the OAuth flow, since the "Connect via OAuth" action is usually a separate button from the form's normal submit action and can bypass validation that only runs on submit.

Refreshing the Authorization

If an account's OAuth authorization with the PSP expires or is revoked (for example, the end user revokes access at the PSP, or the PSP requires periodic re-consent), the account's authorization needs to be refreshed.

To do this, call Create an OAuth redirect URL for an existing account with the ID of the existing account — instead of CreateOauthRedirectUrl, which is used only when creating a new account. Redirect the end user to the returned redirectUrl the same way as in the initial OAuth authorization flow above.

Once the end user completes the authorization with the PSP, PayData stores the refreshed credentials directly on the account. Unlike the initial account creation flow, no separate Update Account call with the auth-reference is required.

info

Because the redirect URL is tied to the existing account, PayData verifies that the re-authorization is for the same account/shop. If a different end user authenticates, or the wrong shop is selected during the PSP's authorization step, PayData rejects the refresh.

Validation

When an account is created the credentials are validated by making a 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).

Best practice: treat ignoreTestErrors as a user-initiated override

Avoid sending ignoreTestErrors: true by default on every request — that hides real credential problems from the end user. Surface the 412 to the end user first, the same as any other validation error, and only retry with ignoreTestErrors: true if the end user actively chooses to proceed anyway. This can be a legitimate and useful debugging/support tool, but setting it unconditionally defeats the point of the validation.

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.

POST /accounttypes/adyen/credentials/validate

ValidateAccountTypeCredentials

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

Request Body

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

Response — HTTP/1.1 200

{
  "success": true,
  "errorCode": null,
  "message": null,
  "errors": []
}