Overview
The Paysafe iOS SDK seamlessly integrates into your mobile app, offering flexibility and full customization.
It ensures data security and PCI compliance while allowing you to design the entire user experience according to your app’s requirements. The SDK manages sensitive payment fields such as card number, CVV, expiry date, year, and month, prioritizing data and PCI security.
Paysafe Group handles the user input and storage of the data. Paysafe iOS SDK uses the Payment API REST APIs to handle the payment. The SDK is built with an idiomatic and modular approach, ensuring a smooth implementation experience.
Advantages
- Paysafe native SDK may provide better PCI scope due to its direct collection of card data within the mobile app. Please consult your Qualified Security Assessor to determine your PCI level.
- You can extensively customize payment forms to match your mobile app design. Create as many translated or localized versions of your payment form as required.
- Embeds naturally and remains invisible.
- Supports processing payments with 3D Secure-enabled cards.
- Supports processing of Cards, Apple Pay, and PayPal.
- No redirection to external webpage for 3DS is required.
- Support native iOS Platform SCA authentication.
Before you begin
Please contact your business relationship manager or reach out to integrations@paysafe.com for credentials to the Business Portal.
To obtain the Public API key from the Business Portal:
- Log in to the Business Portal.
- Go to Integrate > API Keys.
- For public key, click the Copy to copy the API key.
- Your API key will have the following format:
- Key Username - MerchantXYZ
- Key Password -B-tst1-0-51ed39e4-312d02345d3f123120881dff9bb4020a89e8ac44cdfdcecd702151182fdc952272661d290ab2e5849e31bb03deede7e
- Use the same API key for all the Payment Methods.
- You must Base64 encode your public API key before using it in the Payments JS SDK.
- The API key is case-sensitive and sent using HTTP basic authentication.
- To use HTTP basic authentication, you must send the API key credentials using the authorization header with every request.
- You must construct the authorization header as follows:
- Combine the key username and key password into a string separated by a colon. For example, “Key Username:Key Password”.
- The resulting string literal is then encoded using Base64.
- The authorization method and space (“Basic”) are then put before the encoded string.
- For example, using the key username and password examples above, the header is formed as follows - Authorization: Basic TWVyY2hhbnRYWVo6Qi10c3QxLTAtNTFlZDM5ZTQtMzEyZDAyMzQ1ZDNmMTIzMTIwODgxZGZmOWJiNDAyMGE4OWU4YWM0NGNkZmRjZWNkNzAyMTUxMTgyZmRjOTU yMjcyNjYxZDI5MGFiMmU1ODQ5ZTMxYmIwM2RlZWRlN2U=
For additional details, see authentication.
SDK Modules
- PaysafeCardPayments:
- Provides card payments.
- The foundational module, offering core functionalities and utilities essential for the SDK's operations.
- Offers dedicated views to capture and tokenize credit card details securely and straightforwardly.
- Offers customization for individual components and supports accessibility.
- Uses Paysafe3DS for 3D secure authorization, that uses Cardinal SDK.
- Paysafe3DS:
- Specialized for 3D Secure transactions, ensuring secure online payments by adding an authentication layer.
- Streamlines the 3DS challenge process when necessary for a credit card.
- PaysafeApplePay:
- Provides integration with Apple Pay.
- Provides customization for Apple Pay button rendering.
- Apple Pay tokenization through Payments API.
- PaysafeVenmo:
- Provides integration with Venmo.
- Venmo tokenization through Payments API. .
Integrating the iOS SDK
The Paysafe iOS SDK is open source and includes demo for testing the various functionalities. It is compatible with apps supporting iOS 14 or above.
1. In Xcode, select File > Add Packages… and enter https://github.com/paysafegroup/paysafe_sdk_ios_payments_api as the repository URL and select the latest version number.
2. Tick the checkboxes for the specific Paysafe libraries you wish to include.
3. If you look at your app target, you will see that the Paysafe libraries you chose are automatically linked as a framework to your app (see General > Frameworks, Libraries, and Embedded Content).
// In your Swift file
import PaysafeCardPayments
import PaysafeVenmo
import PaysafeApplePay
import Paysafe3DS
// Add in your Podfile
pod 'PaysafePaymentsSDK'
// Or you can import only a single module
pod 'PaysafePaymentsSDK/PaysafeCardPayments'
pod 'PaysafePaymentsSDK/PaysafeVenmo'
pod 'PaysafePaymentsSDK/PaysafeApplePay'
pod 'PaysafePaymentsSDK/Paysafe3DS'
// In your Swift file
import PaysafePaymentsSDK
Setup
After Paysafe iOS package is integrated into your project, setup PaysafeSDK on application start.
import PaysafeCardPayments
// Custom theme example
let theme = PSTheme(
backgroundColor: UIColor(red: 44/255, green: 30/255, blue: 70/255, alpha: 1.0),
borderColor: UIColor(red: 201/255, green: 201/255, blue: 201/255, alpha: 1.0),
focusedBorderColor: UIColor(red: 133/255, green: 81/255, blue: 161/255, alpha: 1.0),
textInputColor: UIColor(red: 214/255, green: 195/255, blue: 229/255, alpha: 1.0),
placeholderColor: UIColor(red: 111/255, green: 77/255, blue: 155/255, alpha: 1.0),
hintColor: UIColor(red: 1.0, green: 1.0, blue: 1.0, alpha: 1.0)
)
PaysafeSDK.shared.setup(
apiKey: apiKey,
environment: .test,
theme: theme)
{ result in
switch result {
case .success:
print("[Paysafe SDK] initialized successfully")
case let .failure(error):
print("[Paysafe SDK] initialize failure \(error.displayMessage)")
}
}
The setup function creates and initializes the Paysafe iOS SDK. Pass the following parameters during its initialization from the application:
Parameter | Required | Type | Description |
---|---|---|---|
theme | False | PSTheme | If theme parameter is not provided, then the default theme is applied. |
environment | True | PaysafeEnvironment | PaysafeEnvironment is an enum type with the following cases:
|
apikey | True | String | The Base64-encoded version of the single-use token API key is used to authenticate with the Payment Hub REST API. |
API Key
The Base64-encoded version of the single-use token API key is used to authenticate with the Payment Hub REST API. Note that this key can be used only to generate single-use tokens for use with the Payments API and has no other API access rights (such as for taking payments). Additionally, it can be exposed publicly in the user's browser.
Environment
The environment string is used to select the environment to use for tokenization. The accepted environments are PRODUCTION (the Paysafe production environment) and TEST (the Paysafe merchant test or sandbox environment).
Do not use real card numbers or other payment instrument details in the Merchant Test environment. It is not compliant with Payment Card Industry Data Security Standards (PCI-DSS) and does not protect cardholder/payee information. Any upload of real cardholder data is strictly prohibited.
Callback error object
The following table describes the contents of the error object:
Parameter | Required | Type | Description |
---|---|---|---|
code | True | String | Error Code |
displayMessage | True | String | Error message for display to customers. |
detailedMessage | True | String | Detailed description of the error (this information should not be displayed to customers). |
correlationId | True | String | Unique error ID to be provided to Paysafe support during investigation. |
Setup errors
Error code | Display messages | Detailed messages | Comments |
---|---|---|---|
9013 | There was an error (9013), please contact our support. | Invalid API key. | The decoded API key does not conform with the format "username:password". |
9167 | There was an error (9167), please contact our support. | The API key should not be empty. | Error message for display to customers. |