Consumer

Introduction

The Consumer integration allows partners to provide their customers with the ability to manage their own wallet.

Configuration Authentication

In order to use Configuration APIs, partners must issue a valid Configuration Token.

The high-level sequence of API calls will be as follows:

1. Issue a configuration token by supplying the Configuration client credentials.

   note

   The authentication details for the calling client are submitted through Basic Auth, encompassing the admin Client ID and Client Secret credentials - both provided by Paysafe business relationship manager.

   Issue a Configuration Token

   Request

   curl --location 'https://api.paysafe.com/digitalwallets/v1/auth/brands/{{brand}}/token' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --header 'Authorization: Basic {{encodeBase64(client_id:client_secret)}}' \
   --data-urlencode 'grant_type=client_credentials'

   ---

   Response

   {
     "access_token": "{{configuration-token}}",
     "expires_in": 900,
     "token_type": "Bearer",
     "scope": "whitelabelWallet"
   }

2. You get a configuration token in the response, with a very limited lifespan.

3. Use the configuration token for a configuration task.

• SDK Configuration
• Send an Embedded or Hybrid SCA Challenge
• Submit an Embedded or Hybrid SCA Attempt
• Others

Perform Configuration

One of the most important use cases of the Configuration Token is the configuration of the Paysafe Wallet SDK.

Operations Sequence

The sequence of API calls will be as follows:

1. Generate a Configuration Token using the client credentials flow. The authentication details for the calling client are submitted through Basic Auth, encompassing the configuration client id and client secret credentials - both provided by Paysafe business relationship manager.

Issue a Configuration Token

Request

 curl --location 'https://api.paysafe.com/digitalwallets/v1/auth/brands/{{brand}}/token' \
 --header 'Content-Type: application/x-www-form-urlencoded' \
 --header 'Authorization: Basic {{encodeBase64(client_id:client_secret)}}' \
 --data-urlencode 'grant_type=client_credentials'

---

Response

 {
   "access_token": "{{configuration-token}}",
   "expires_in": 900,
   "token_type": "Bearer",
   "scope": "whitelabelWallet"
 }

2. You get a configuration token in the response, with a very limited lifespan.

3. Provide the token to configure the Paysafe SDK, consulting the provided examples tailored to the front-end technology for assistance.

4. The SDK will create and store a digital identity for the device, called digital fingerprint, to improve the overall fraud detection capabilities of the SDK.

5. You obtain a digital fingerprint necessary for authenticating the user.

Customer Authentication

In order to use the Consumer APIs (B2C APIs), partners must issue a valid Customer Token.

note

The Customer Token is a token with broad access, scoped to a specific customer. It is designed for usage by the Paysafe Wallet SDK and allows customers to manage their own wallets.

This token possesses broader permissions for access to customer-specific resources or functionalities.

If a Customer Token, which has access to sensitive scopes, is compromised, the damage is limited to that particular customer.

Partners can issue a Customer Token by using one of the following OAuth2 authorization grant types:

• Token Exchange
• Authorization Code

Token Exchange

The urn:ietf:params:oauth:grant-type:token-exchange grant type is a method of issuing a Customer Token based on the trust between the partner and Paysafe.

This method allows the partner to exchange a customer token from their own system (subject_token) for a Paysafe customer token.

• The Partner Customer Token (subject_token) is a token issued by the partner's authorization server, representing the customer in the partner's system.
• The Paysafe Customer Token is a token issued by the Paysafe authorization server, representing the same customer in the Paysafe Embedded Wallet system.

note

In order to establish trust, the Partner Customer Token must adhere to the JWT Registered Claims as described by RFC 7519 Section 4.1.

For Token Exchange to work, the following must be provided by the partner:

• JWT Claims in the Partner Customer Token:
  • iss (Issuer): The issuer of the token (partner authorization server).
  • sub (Subject): The subject of the token (partner customer), which matches the External ID of the customer in the Paysafe Embedded Wallet.
• JWKS Url or Public Key (used to verify the signature of the Partner Customer Token):
  • Public Key (for static validations) to verify the signature of the Partner Customer Token.
  • JWKS Url containing the public keys (for dynamic validations, with no need for extra support in case of key rotations on partner's end).

Operations Sequence

The sequence of API calls will be as follows:

1. Authenticate the user for wallet access by supplying client credentials, subject token, and digital fingerprint through the token exchange flow:

   note

   The authentication details for the calling client are submitted through Basic Auth, encompassing the admin Client ID and Client Secret credentials - both provided by Paysafe business relationship manager.

   • The subject token represents the identity of the partner customer on behalf of whom the request is being made.
   • The digital fingerprint is created in the SDK configuration phase. It enhances the ability of systems to identify device and network irregularities, thereby enhancing overall fraud detection capabilities.
   Issue an Access Token (Token Exchange)

   Request

   curl --location 'https://api.paysafe.com/digitalwallets/v1/auth/brands/{{brand}}/token' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --header 'Authorization: Basic {{encodeBase64(client_id:client_secret)}}' \
   --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
   --data-urlencode 'subject_token={{partner-customer-token}}' \
   --data-urlencode 'digital_fingerprint=bb229878-c877-4cc3-91c4-2030c34be28a'

   ---

   Response

   {
     "access_token": "{{customer-token}}",
     "expires_in": 900,
     "refresh_token": "{{refresh-token}}",
     "refresh_expires_in": 1800,
     "token_type": "Bearer",
     "scope": "whitelabelWallet"
   }

2. You get a customer token in the response, along with a refresh token. They have a short lifespan to ensure better security.

3. The customer token should be supplied to the Paysafe SDK to authenticate the user for SDK operations. Refer to the provided examples based on the front-end technology for guidance.

• Authenticate User - Web
• Authenticate User - Android
• Authenticate User - iOS

4. The SDK is authenticated and prepared to access customer-specific data or perform sensitive actions.

Authorization Code

Feature in development

To generate a new customer token with access to sensitive scopes, the partner backend needs to initiate a token request with authorization_code grant type and provide an authorization code. The code is obtained through the partner's web/mobile application after a successful end-user authentication in the Paysafe Authentication UI.

The authorization code flow is achieved by the successful completion of two steps (compared to one in the token exchange flow).

1. Execution of the Authorize request in a suitable environment (like a browser), which opens up the Paysafe Authentication UI for the user to authenticate. The user enters their credentials and the result is a redirect back to the partner's application and the generation of the authorization code.
2. Execution of the Token request, which exchanges the authorization code for a customer token.

Home URL

The Home URL is the default URL that is used by the Paysafe Authentication UI in order to allow the user to go back to the partner's application. An example scenario would be when the partner has provided an invalid redirect_uri in the Authorize request.

The Home URL must be shared with Paysafe in advance, so it is available to the user for its intended purposes.

note

The Home URL is configured once and is used for all Authorize requests automatically.

Redirect URI

The redirect_uri that is provided for the construction of the Authorize request must be shared with Paysafe in advance, so it can be whitelisted for improved security. Paysafe will use this redirect_uri to redirect the user back to the partner's application after a successful authentication.

note

In case of an error during the Authorize request execution, the redirect_uri is used for error recovery:

• If the redirect_uri is invalid (e.g. not whitelisted), the user will be redirected to a Paysafe failure page.
• If the redirect_uri is valid, the user will be redirected back to the redirect_uri with error and error_description query parameters, as described by RFC 6749 §4.1.2.1.

Reach out to the Paysafe business relationship manager for the setup of the redirect_uri.

PKCE

PKCE (RFC 7636) is an extension to the Authorization Code flow to prevent CSRF and authorization code injection attacks.

The PKCE specification outlines two main components:

• code_verifier: High-entropy cryptographic random string, as described by RFC 7636 §4.1. The code_verifier is passed to the Token request.
• code_challenge: Derived from the code_verifier and based on the code_challenge_method, as described by RFC 7636 §4.2. The code challenge is passed to the Authorize request.

note

• The client is responsible for the generation of both the code_verifier and the code_challenge prior to initiating the Authorization Code flow.
• The Paysafe Authentication Server is responsible for verifying that the code_verifier provided in the Token request is the value that was used to initially generate the code_challenge provided in the Authorize request.

State

The state parameter is an opaque value used by the client to maintain state between the request and the callback, as described by RFC 6749 §4.1.1. It can be used for the prevention of CSRF attacks and for restoring the previous state of the application (e.g. encoding basic session information in it). The client includes this value when initiating the Authorize request and the server includes it when redirecting the user back to the client (through the redirect_uri).

note

The client is responsible for the generation of the state prior to initiating the Authorization Code flow and for verifying it after the user is redirected back to the client.

Operations Sequence

The sequence of API calls will be as follows:

Web

1. Get the authentication details from the Web SDK by supplying the necessary parameters. This will result in receiving an object that contains a ready to use Authorize URI.

2. Redirect the end-user to the received Authorize URI, which will open the Paysafe Authentication UI for the user to authenticate.

   note

   This step is performed by the partner, since this way they are in control of the Web user experience and the way that the Paysafe Authentication UI will be served to the end-user.

3. The end-user enters their credentials in the Paysafe Authentication UI and attempts to authenticate.

4. After a successful authentication, the Paysafe Authentication UI will redirect the user back to the redirect_uri provided in the Authorize request, with the authorization code and state as query parameters.

5. The partner application extracts the state from the query parameters and verifies that it matches the state that was provided to the Authorize request.

6. The partner application extracts the authorization code from the query parameters and calls their backend to exchange the code for the customer token.

7. Authenticate the user for wallet access by supplying the respective parameters through the authorization code flow.

   • The authentication details for the calling client are submitted through Basic Auth by including your client id and client secret credentials, both provided by Paysafe business relationship manager.
   • The client_id and client_secret are used to verify the correct authorization code client has been used.
   • The PKCE code_verifier represents the code verifier, based on which the code_challenge was generated. PKCE is used for an increased security and to prevent interception attacks.
   • The redirect_uri must match the one used in the Authorize request.
   • The code must be the one received as a result of the redirect from the Paysafe Authentication UI.
   • The digital fingerprint is created in the SDK configuration phase, enhancing the ability of systems to identify device and network irregularities, thereby enhancing overall fraud detection capabilities.

Mobile

1. Redirect the end-user to the Authorize URI directly from the Mobile SDK by supplying the necessary parameters. This will open the Paysafe Authentication UI for the user to authenticate.

   note

   This step is performed by the Mobile SDK due to the specification of the mobile environments and their handling of user operations.

2. The end-user enters their credentials in the Paysafe Authentication UI and attempts to authenticate.

3. After a successful authentication, the Paysafe Authentication UI will redirect the user back to the redirect_uri provided in the Authorize request, with the authorization code and state as query parameters.

4. The partner application extracts the state from the query parameters and verifies that it matches the state that was provided to the Authorize request.

5. The partner application extracts the authorization code from the query parameters and calls their backend to exchange the code for the customer token.

6. Authenticate the user for wallet access by supplying the respective parameters through the authorization code flow.

   • The authentication details for the calling client are submitted through Basic Auth by including your client id and client secret credentials, both provided by Paysafe business relationship manager.
   • The client_id and client_secret are used to verify the correct authorization code client has been used.
   • The PKCE code_verifier represents the code verifier, based on which the code_challenge was generated. PKCE is used for an increased security and to prevent interception attacks.
   • The redirect_uri must match the one used in the Authorize request.
   • The code must be the one received as a result of the redirect from the Paysafe Authentication UI.
   • The digital fingerprint is created in the SDK configuration phase, enhancing the ability of systems to identify device and network irregularities, thereby enhancing overall fraud detection capabilities.

The token request will return the customer token and the refresh token.

Issue an Access Token (Authorization Code)

Request

 curl --location 'https://api.paysafe.com/digitalwallets/v1/auth/brands/{{brand}}/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Authorization: Basic {{encodeBase64(client_id:client_secret)}}' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'client_id={{client_id}}' \
  --data-urlencode 'client_secret={{client_secret}}' \
  --data-urlencode 'code_verifier={{code_verifier}}' \
  --data-urlencode 'redirect_uri={{redirect_uri}}' \
  --data-urlencode 'code={{code}}' \
  --data-urlencode 'digital_fingerprint=bb229878-c877-4cc3-91c4-2030c34be28a'

---

Response

{
  "access_token": "{{customer-token}}",
  "expires_in": 900,
  "refresh_token": "{{refresh-token}}",
  "refresh_expires_in": 1800,
  "token_type": "Bearer",
  "scope": "whitelabelWallet"
}

Refresh Token

The customer token remains valid for a short period of time. Beyond this timeframe, the customer needs to undergo re-authentication to access customer-specific information or execute sensitive actions. There are two available choices for achieving this:

• Following either the Token Exchange or the Authorization Code process (as detailed in the preceding sections).
• Refreshing the already expired customer token. During the API call, there is no need to supply a digital fingerprint for this process to work.

Operations Sequence

The sequence of Refresh Token API calls will be as follows:

1. User obtains a customer token and a refresh token during the initial authentication process (the validity period of the refresh token is longer than the customer token).

2. Your backend application utilizes Basic Auth to send a request to Paysafe authorization server's token endpoint, incorporating the same client credentials employed for token exchange or authorization code flow to obtain authorization using the refresh token grant.

Issue an Access Token (Refresh Token)

Request

curl --location 'https://api.paysafe.com/digitalwallets/v1/auth/brands/{{brand}}/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic {{encodeBase64(client_id:client_secret)}}' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token={{refresh-token}}'

---

Response

{
  "access_token": "{{customer-token}}",
  "expires_in": 900,
  "refresh_token": "{{refresh-token}}",
  "refresh_expires_in": 1800,
  "token_type": "Bearer",
  "scope": "whitelabelWallet"
}

3. If the refresh token is valid, a new customer token is issued, accompanied by a new refresh token.

4. The refreshed customer token should be supplied to the Paysafe SDK to re-authenticate the user for SDK operations. Refer to the provided examples based on the front-end technology for guidance.

5. The SDK can use the new customer token to continue accessing protected resources without requiring the user to re-authenticate.

6. The process can be repeated as long as the refresh token remains valid.

info

Both methods of user re-authentication are equally secure and can be employed based on your specific requirements and the setup of your application.