Skip to main content

Introduction

Introduction​

Paysafe Wallet SDK offers a lower TCO and TCD solution for providing wallet services to end users in partner applications. It is directly connected to User Facing Wallet APIs and does not require partners to host the wallet functionalities provided by the SDK in their backend systems.

SDK Use CasesSDK Use CasesSDK Use CasesSDK Use Cases

The Paysafe Wallet SDK is provided for all popular front end technologies, like web and mobile (Android, iOS).

note

Paysafe Wallet SDK is available only for regular customers and can not be used to perform actions on wallets owned by legal entities and merchants.

To leverage the Paysafe Wallet SDK in your applications you need to properly configure and authenticate it, so it can access the customer wallet.

The configuration and authentication process is a two-step process implemented with the support of your backend and ensures secure access to the customer data.

Use cases​

Paysafe Embedded Wallet offers two APIs to interact with it:

  • Business APIs - Also called B2B APIs are secured using OAuth Bearer Token and allow merchant full control over all embedded wallet functionalities for all customers in the Embedded Wallet system.
  • User Facing APIs - Also called B2C APIs are secured using OAuth Bearer Token scoped to a specific customer wallet. The customer can only see and perform wallet operations over the wallet he owns.

When you build your solutions using Paysafe Embedded Wallet, you own the customer experience. So you can choose which wallet service to expose to the end users and how to style and shape the user interface exposed.

info

When using Business APIs in addition to building the user interface for the wallet functionalities of your application, you must also develop and host the required backend infrastructure.

Development and hosting of all required backend logic for the wallet operations exposed to end users results in a higher Total Cost of Development (TCD) and Total Cost of Ownership (TCO).

B2B Use CasesB2B Use CasesB2B Use CasesB2B Use Cases

In all scenarios, where partner does not need to implement advanced business logic on top of the standard wallet functionalities it is advised to leverage the Paysafe Wallet SDK, that connects to the User Facing APIs.

User Facing APIs​

User Facing APIs are built to support and serve the Paysafe Wallet SDK use cases.

note

It is not recommended to call the User Facing APIs directly in your application.

User Facing APIs utilize OAuth 2.0 Bearer Tokens for request authentication, necessitating the inclusion of a bearer token in all API calls.

Security Tokens​

Paysafe partners, utilizing the supplied SDK, should use two types of API security tokens:

  • Configuration Tokens are weak, application level API tokens, that are not restricted to a specific end customer. They are used to configure the SDK, so it can reuse the provided configuration for the lifecycle of the partner’s application.
  • Customer Tokens are end-customer specific, and only allow access to resources associated with a specific customer. They facilitate a smooth user experience by enabling direct communication from end-user devices and executing actions on behalf of the designated user.
note

An invalid, missing or expired token will result in HTTP 401 Unauthorized responses.

Paysafe provides two sets of OAuth 2.0 client id and client secret credentials, specifically designed for either the sandbox or live environment, tailored to the specific token type (configuration or customer). When initiating an access token request, ensure that the Authorization header using the Basic scheme is configured with the relevant credentials corresponding to the environment in which the call is being made and the desired token type.

info

For additional details, please refer to Basic Authentication on Wikipedia.

Upon providing these credentials, the Paysafe authorization server issues a bearer access token. This token serves as the key for authorizing API requests, empowering the SDK to perform actions on behalf of and with the explicit approval of the resource owner.

SDK Configuration​

The SDK configuration acts as a prerequisite that precedes onboarding and authenticating the user within the Wallet, accomplished by obtaining a configuration token. It is used to configure the SDK, enhance the overall fraud detection capabilities, and utilize the provided settings throughout the lifecycle of the partner's application.

note

Configuration tokens are tokens with limited access, specifically designed for configuring the SDK and lacking broader permissions to access other resources or functionalities.

During the SDK configuration, a digital identity for the device, called digital fingerprint, is created and stored, which must be provided during the user onboarding and authentication process. The digital fingerprint enhances the ability of systems to identify device and network irregularities, thereby improving overall fraud detection capabilities.

Client Credentials​

Creating a configuration token necessitates the involvement of the partner's backend, which should trigger a client credentials request.

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 {{client_id:client_secret}}' \
 --data-urlencode 'grant_type=client_credentials'

Response

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

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

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

  3. 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.

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

SDK Configuration Client CredentialsSDK Configuration Client CredentialsSDK Configuration Client CredentialsSDK Configuration Client Credentials

SDK User Authentication​

To ensure secure access to customer data by the SDK, it is necessary to provide a customer token. This token enables access to customer-specific information and the execution of sensitive actions (mostly related to funds movement). Customer tokens exclusively permit access to resources linked to the specific customer for whom the token was generated.

note

Customer tokens restrict access to resources not linked to the authenticated customer. If a customer token, which has access to sensitive scopes, is compromised, the damage is limited to that particular customer.

To generate a new customer token with access to sensitive scopes, the partner backend needs to initiate a token request. This can be achieved by using one of the OAuth2 authorization grant types:

  • Token Exchange
  • Authorization Code

Token Exchange​

To generate a new customer token with access to sensitive scopes, the partner backend needs to initiate a token exchange request by providing the customer's access token.

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:

    • 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 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, enhancing 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 {{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"
}

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

  2. 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.

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

info

To verify the signature of the subject token presented in the token exchange process, you need to send to Paysafe either your JWT public keys (for static validations) or the JWKS endpoint containing the public keys (for dynamic validations, with no need for extra support in case of key rotations on your end).

SDK User Authentication Token ExchangeSDK User Authentication Token ExchangeSDK User Authentication Token ExchangeSDK User Authentication Token Exchange

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.

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:

  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.

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 {{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"
}
SDK User Authentication - Authorization CodeSDK User Authentication - Authorization CodeSDK User Authentication - Authorization CodeSDK User Authentication - Authorization Code

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 {{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"
}

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

  2. 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.

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

  4. 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.

SDK User Authentication Refresh TokenSDK User Authentication Refresh TokenSDK User Authentication Refresh TokenSDK User Authentication Refresh Token