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.
The Paysafe Wallet SDK is provided for all popular front end technologies, like web and mobile (Android, iOS).
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.
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).
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.
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.
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.
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.
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. The sequence of API calls will be as follows:
- 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"
}
-
You get a configuration token in the response, with a very limited lifespan.
-
Provide the token to configure the Paysafe SDK, consulting the provided examples tailored to the front-end technology for assistance.
-
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.
-
You obtain a digital fingerprint necessary for authenticating the user.
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.
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.
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. The sequence of API calls will be as follows:
-
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"
}
-
You get a customer token in the response, along with a refresh token. They have a short lifespan to ensure better security.
-
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.
-
The SDK is authenticated and prepared to access customer-specific data or perform sensitive actions.
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).
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 the Token Exchange process (as detailed in the preceding section).
- Refreshing the already expired customer token. During the API call, there is no need to supply a digital fingerprint for this process to work.
The sequence of Refresh Token API calls will be as follows:
-
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).
-
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 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"
}
-
If the refresh token is valid, a new customer token is issued, accompanied by a new refresh token.
-
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.
-
The SDK can use the new customer token to continue accessing protected resources without requiring the user to re-authenticate.
-
The process can be repeated as long as the refresh token remains valid.
Both methods of user re-authentication are equally secure and can be employed based on your specific requirements and the setup of your application.
