Skip to main content

Getting Started

API Basics​

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.

Authentication​

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:

  1. The Key Username and Key Password are combined into a string separated by a colon, e.g.,“Key Username:Key Password”.
  2. The resulting string literal is then encoded using Base64 (to allow sending of special characters).
  3. The authorization method and a 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 integrations@paysafe.com for API keys and Test/Production accounts.

note

All your APIs will use the same API key.

Request Signing​

Some endpoints require a digital signature.

Please refer to the Request Signing page for more details.

Testing​

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 us. Your test account has access to the test version of the Paysafe business portal, where you can view the status of your test transactions.

Test URL​

To test your integration with Paysafe, use the following Test URLs:

  • https://api.test.paysafe.com/paymenthub/v1/
  • https://api.test.paysafe.com/digitalwallets/v1/

For example:

  • https://api.test.paysafe.com/paymenthub/v1/payments/{payment_id}

Going live​

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.

Production URL​

To process live requests with Paysafe, use the following Production URL:

  • https://api.paysafe.com/paymenthub/v1/
  • https://api.paysafe.com/digitalwallets/v1/

For example:

  • https://api.paysafe.com/paymenthub/v1/payments/{payment_id}
  • https://api.paysafe.com/digitalwallets/v1/customers

Pagination​

In the case where an API GET request returns multiple results, the response data is paginated. The input for paginated query contains two parameters:

  • limit - This is the number of records to return. Defaults to 10 and maximum is 50.
  • offset - This is the starting position of the response, where 0 is the first record. Default = 0.
note

The total number of records is not returned. If numberOfRecords < limit, this means no further pages are available.

The number of previous pages can be calculated by dividing offset to limit. This object contains meta property in the response, that allows to determine the page location. More information can be found in the PagingResultMeta.

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​

ISO standards add value by providing the common business process data semantics to be used in the API based exchanges.

Please refer to ISO Standards for Global Invalid Characters, ISO Standards, Currency Codes, Province Codes, State Codes, and Country Codes.