The API is constructed around REST and has the following features:
Definite resource-oriented URLs
Receives JSON-encoded request bodies
Returns JSON-encoded responses
Communicates using standard HTTP response codes, authentication, and verbs.
Message body: This must contain valid Paysafe JSON objects as required for the type of request. Not all API calls require a message body. For example, the GET requests do not require a body.
Resource ID: Identifies the unique ID of a resource.
Paysafe's REST API uses API keys to authenticate your request in the following format:
- Key Username – MerchantXYZ
- Key Password – 20881dff9bb4020a89e8ac44
The case-sensitive API key is sent using HTTP Basic Authentication. To use HTTP Basic Authentication, you must send the API key credentials using the Authorization header with every request.
The Authorization header is constructed as follows:
- The Key Username and Key Password are combined into a string separated by a colon, e.g.,“Key Username:Key Password”.
- The resulting string literal is then encoded using Base64 (to allow sending of special characters).
- The authorization method and а space (i.e., “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 TWVyY2hhbnRYWVo6MjA4ODFkZmY5YmI0MDIwYTg5ZThhYzQ0
For additional details, please refer to Basic Authentication on Wikipedia.
Note: Your Production API key will be different from your Test API key. Contact your account manager for details. You must keep your API keys safe and ensure that it is used appropriately for your needs.
Get Your Secret API Key
Please contact your business relationship manager or reach out to firstname.lastname@example.org for API keys and Test/Production accounts.
Note: All your APIs will use the same API key.
Test accounts enable you to process API transactions that mirror the functionality of the Production environment.
Transactions processed in the Test environment are executed on a simulator. Depending on the information provided with the transaction request, the simulator returns either a successful (approved) or failed (declined) response.
With the API, you can:
- Verify support for all the operation types that you require.
- Review all common errors as well as unique errors that may occur for each operation.
- Verify the length and format for all attributes you send.
For access to Test accounts and credentials, contact your account manager or reach out to email@example.com. Your Test account has access to the Test version of the Paysafe Business Portal, where you can view the status of your Test transactions.
To test your integration with Paysafe, use the following Test URLs:
Once you are satisfied with your integration to the Test environment, you must repeat the configuration changes made to your Test account on your Production account.
Note: You cannot use your Test credentials to process transaction requests in the Production environment.
Go Live Checklist
- You must have a production account and access to Business Portal.
- You must have a Secret API Key for the production environment.
- You must have Webhooks configured for all the events.
- You must use the Production URL for your API calls.
To process live requests with Paysafe, use the following Production URL:
In the case where an API GET request returns multiple results, Paysafe returns the first 10 records by default and uses HATEOAS links to provide page navigation. In addition to the default behavior, it is also possible to control the number of results and starting point by passing in query parameters as described in this section.
Global Invalid Characters
You must not include any of the characters in this table as values in any of your request parameters. Object. If you do, your request will result in an error.
ISO standards add value by providing the common business process data semantics to be used in the API based exchanges. This section presents you with codes for four areas - Currency, Province, State, and Country.
Please refer ISO Standards for Global Invalid Characters, ISO Standards, Currency Codes, Province Codes, State Codes, and Country Codes.
Features in development
Documentation for new features and capabilities currently in development is exposed as means of collecting customer feedback. The feedback allows Paysafe to evolve the product and decide on future product direction.
- might not get released in general availability for all customers
- might get changed before being released in general availability
- might be enabled in a test environment for selected Paysafe customers and partners
- might require contract amendments to be accessible to your environment
Note: Parts of the API that are part of a new unreleased feature would be annotated with
Contact your Paysafe account manager for more details on the product roadmap.