Skip to main content

User Credentials
Feature in development

Introduction​

The Paysafe Embedded Wallet allows the partners to integrate with Paysafe's SDKs in order to provide a fully-fledged end-user experience.

The user credentials are a vital component in the Embedded Wallets ecosystem. The successful setup of these credentials is a prerequisite for allowing the end-users to log into their wallets and perform wallet operations.

Setup PIN​

The Setup PIN process is a mandatory step to completely finalize the extended user onboarding process and allow the user to access their wallet.

The Customer Credentials Management Process will allow the partner to redirect their users to the Paysafe Credentials UI. There they can set up their credentials after which they would be automatically logged into their wallet and redirected back to the partner's application.

warning

The involvement of the Paysafe Web and Mobile SDKs is different in terms of the completion of the Customer Credentials Management Process for Setup PIN!

  • Web: The Web SDK is not involved in the Customer Credentials Management Process at all. It is the responsibility of the partner to redirect the user to the Paysafe Credentials UI and extract the Customer Token from the query parameters after the user is redirected back to the partner's application. The Web SDK only then comes into play to set up the wallet with the received Customer Token.
  • Mobile: The Mobile SDK is involved in the Customer Credentials Management Process during its initiation phase. It is the responsibility of the partner to provide the Paysafe Credentials UI URL to the SDK and it will automatically redirect the user to the Paysafe Credentials UI. The partner should extract the Customer Token from the query parameters after the user is redirected back to the partner's application. The Mobile SDK is then used to set up the wallet with the received Customer Token.

The flow is achieved by the successful completion of the following steps:

  1. Perform User Onboarding successfully
  2. Initiate Customer Credentials Management Process
  3. Redirect the user to the Paysafe Credentials UI
  4. Paysafe Sends OTP Code to the user
  5. User provides the received OTP code and chooses a PIN
  6. User is auto-logged in and redirected back to the partner's application

User Onboarding​

The user must already be onboarded in the Paysafe Embedded Wallets ecosystem. This is achieved by the successful completion of the Customer Onboarding process.

Initiate a Customer Credentials Management Process​

note

After a successful Customer Onboarding, the partner must Initiate a Customer Credentials Management Process. Keep in mind that these two steps are independently executed, since the users could decide to set up their credentials at a later time.

The partner triggers Initiate a Customer Credentials Management Process by providing the Flow and Return URL parameters (along with others). The Return URL that is provided must be shared with Paysafe in advance, so it can be whitelisted for improved security. Paysafe will use this Return URL to redirect the user back to the partner's application after a successful completion of the customer credentials management process.

Initiate a Customer Credentials Management Process (Setup PIN)

Request

 curl --request POST \
  --url https://api.paysafe.com/digitalwallets/v2/customers/{{customerId}}/credentials \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{admin-token}}' \
  --data '{
      "language": "en-US",
      "flow": "PIN_SETUP",
      "returnUrl": "https://some-process.partner.com",
      "deviceInfo": {
          "appType": "WEB_APP",
          "threatMetrixSessionId": "5219bd12-cd4c-4d24-8281-51acf3bea9e0"
      }
  }'

Response

{
 "language": "en-US",
 "flow": "PIN_SETUP",
 "returnUrl": "https://some-process.partner.com",
 "redirectUrl": "https://auth.paysafe.com/v1/auth/brands/{brandIdentity}/credentials?lang=en_US&fingerprint=19e0abfb...&flow=PIN_SETUP&token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lk..&returnURL=https://.......",
 "deviceInfo": {
   "appType": "WEB_APP",
   "threatMetrixSessionId": "5219bd12-cd4c-4d24-8281-51acf3bea9e0"
 }
}

Open Paysafe Credentials UI​

The partner has received a Redirect URL in the response from the Initiate a Customer Credentials Management Process request and redirects the user to this URL.

Send OTP Code​

The user will receive an OTP Code (sent by Paysafe) with the ability to resend it if needed.

note

Each new OTP challenge/code creates a new internal verification process and a new process can only be initiated a limited number of times. If this limit is exceeded, the user will not be able to request a new OTP code for some time. After the cooldown period ends, the attempts counter is reset and the verification process can be started again.

The first challenge is sent with the initial load of the Paysafe Credentials UI.

User Setup PIN​

The user provides the received OTP Code and chooses a PIN for their wallet.

note

Once a verification process (initiated in the Send OTP Code step) for a specific customer credentials management process is initiated and active (not expired or failed), the user has a limited number of attempts to complete it (e.g. enter the OTP code). If this limit is reached, no further verification attempts for the same verification process are accepted and are automatically denied. There is no cooldown period and the process is marked as failed.

To retry the verification, a new verification process must be started, as described in the Send OTP Code step. After that the user can attempt the verification again.

After the successful OTP Code verification, the user is prompted to choose their PIN and submit it.

User Auto-login​

After the successful PIN setup, the user is automatically logged in and redirected back to the partner's application. The auto-login process results in generating a Customer Token. The token is returned to the partner as a query parameter when redirecting back to the their application via the Return URL (provided in the Initiate a Customer Credentials Management Process request).

After the successful redirect to the partner's application, the partner can Configure the SDK and use the Customer Token to Authenticate User to allow them to perform wallet operations.

Paysafe Wallet Setup PIN & First LoginPaysafe Wallet Setup PIN & First LoginPaysafe Wallet Setup PIN & First LoginPaysafe Wallet Setup PIN & First Login

Reset PIN​

The Reset PIN process allows unauthenticated users to reset their PIN.

The Customer Credentials Management Process will allow the partner to redirect their unauthenticated users to the Paysafe Reset Credentials UI. There they can reset their credentials after which they would be redirected back to the application that initiated the reset in the first place.

note

The Paysafe Reset Credentials UI provides a flexible end-user journey that can be triggered in one of two ways:

  • The partner initiates the Customer Credentials Management Process and provides the Paysafe Reset Credentials UI URL to the Authorization Code flow. This will allow the user to trigger the Reset PIN process from the Paysafe Authentication UI itself. The user will be returned back to the Paysafe Authentication UI after the Reset PIN process has been completed, so they can log into their wallet with the new PIN. Upon success, they will be redirected back to the Partner Application.
  • The partner initiates the Customer Credentials Management Process and the Partner Application redirects the user to the Paysafe Reset Credentials UI. This will allow the user to be returned back to the Partner Application after the Reset PIN process has been completed. After that, the partner would trigger the Authorization Code flow, so the user can log into their wallet with the new PIN. Upon success, they will be redirected back to the Partner Application.
warning

The involvement of the Paysafe Web and Mobile SDKs is different in terms of the completion of the Customer Credentials Management Process for Reset PIN!

  • Web: The Web SDK is not involved in the Customer Credentials Management Process at all. It is the responsibility of the partner to do one of two things:
    • Provide the Paysafe Reset Credentials UI URL to the Authorization Code flow and trigger it.
    • Redirect the user to the Paysafe Reset Credentials UI themselves and trigger the Authorization Code flow after that.

In the end, the partner should extract the code from the query parameters after the user is redirected back to the partner's application, so they can exchange it for the Customer Token. The Web SDK only then comes into play to set up the wallet with the received Customer Token.

  • Mobile: The Mobile SDK is involved in the Customer Credentials Management Process during its initiation phase. It is the responsibility of the partner to do one of two things:
    • Provide the Paysafe Reset Credentials UI URL to the Authorization Code flow and trigger it.
    • Provide the Paysafe Reset Credentials UI URL to the SDK for a standalone pin reset in which case it will automatically redirect the user to the Paysafe Reset Credentials UI.

In the end, the partner should extract the code from the query parameters after the user is redirected back to the partner's application, so they can exchange it for the Customer Token. The Mobile SDK is then used to set up the wallet with the received Customer Token.

The flow for Reset PIN through the Paysafe Authentication UI is achieved by the successful completion of the following steps:

  1. Initiate Customer Credentials Management Process for an existing user
  2. Redirect the user to the Paysafe Authentication UI
  3. User clicks the Reset PIN button and they are redirected to the Paysafe Reset Credentials UI
  4. Paysafe Sends OTP Code to the user
  5. User provides the received OTP code and chooses a new PIN
  6. User is redirected back to the Paysafe Authentication UI
  7. User enters their new credentials to login and are redirected back to the partner's application

Initiate a Customer Credentials Management Process​

The partner triggers Initiate a Customer Credentials Management Process by providing the Flow parameter (along with others).

note

The Return URL must be provided only if the partner wants to redirect the user back to their application after the completion of the Customer Credentials Management Process. If the Reset PIN is triggered from the Authorization Code flow, Paysafe will override the Return URL (even if provided) to redirect the user back to the Paysafe Authentication UI after a successful completion of the customer credentials management process.

The partner's Return URL that is provided must be shared with Paysafe in advance, so it can be whitelisted for improved security.

Initiate a Customer Credentials Management Process (Reset PIN)

Request

 curl --request POST \
  --url https://api.paysafe.com/digitalwallets/v2/customers/{{customerId}}/credentials \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{admin-token}}' \
  --data '{
      "language": "en-US",
      "flow": "PIN_RESET",
      "deviceInfo": {
          "appType": "WEB_APP",
          "threatMetrixSessionId": "5219bd12-cd4c-4d24-8281-51acf3bea9e0"
      }
  }'

Response

{
 "language": "en-US",
 "flow": "PIN_RESET",
 "redirectUrl": "https://auth.paysafe.com/v1/auth/brands/{brandIdentity}/credentials?lang=en_US&fingerprint=19e0abfb...&flow=PIN_RESET&token=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lk..&returnURL=https://.......",
 "deviceInfo": {
   "appType": "WEB_APP",
   "threatMetrixSessionId": "5219bd12-cd4c-4d24-8281-51acf3bea9e0"
 }
}

Open Paysafe Authentication UI​

The partner has received a Redirect URL in the response from the Initiate a Customer Credentials Management Process request and provides it to the Authorization Code flow. After that the user should be redirected to the Paysafe Authentication UI.

Redirect to Paysafe Reset Credentials UI​

The user triggers the Reset PIN process from the Paysafe Authentication UI itself and this will redirect them to the Paysafe Reset Credentials UI.

Send OTP Code​

The user will receive an OTP Code (sent by Paysafe) with the ability to resend it if needed.

note

Each new OTP challenge/code creates a new internal verification process and a new process can only be initiated a limited number of times. If this limit is exceeded, the user will not be able to request a new OTP code for some time. After the cooldown period ends, the attempts counter is reset and the verification process can be started again.

The first challenge is sent with the initial load of the Paysafe Credentials UI.

User Reset PIN​

The user provides the received OTP Code and chooses a PIN for their wallet.

note

Once a verification process (initiated in the Send OTP Code step) for a specific customer credentials management process is initiated and active (not expired or failed), the user has a limited number of attempts to complete it (e.g. enter the OTP code). If this limit is reached, no further verification attempts for the same verification process are accepted and are automatically denied. There is no cooldown period and the process is marked as failed.

To retry the verification, a new verification process must be started, as described in the Send OTP Code step. After that the user can attempt the verification again.

After the successful OTP Code verification, the user is prompted to choose their new PIN and submit it.

Return to Paysafe Authentication UI​

After the successful Reset PIN process, the user is redirected back to the Paysafe Authentication UI to login with their new credentials.

User Login​

The login process results in generating the code and state parameters. They are returned to the partner as a query parameter when redirecting back to the their application via the Redirect URI (provided in the Authorization Code flow).

After the successful redirect to the partner's application:

  • The state parameter should be verified by the partner in order to prevent CSRF attacks and maintain context between the request and callback as described by RFC 6749 §4.1.1
  • The code is exchanged for the Customer Token.

The partner can then Configure the SDK and use the Customer Token to Authenticate User to allow them to perform wallet operations.

Paysafe Wallet Reset PINPaysafe Wallet Reset PINPaysafe Wallet Reset PINPaysafe Wallet Reset PIN

Change PIN​

The Change PIN process allows authenticated users to change their PIN.