Search Overlay
Searchbox clear search filters ESC
Filter PreferencesClear

No results found

Get Started

The Payments API helps you to easily and securely process payments from your customers using one single API – Payments API. Connect your application directly to the Payments API to process a full suite of payment methods that are REST-based.

To get started with Payment APIs, follow these steps:

  1. Get Your API Key
  2. Understand Payment Handles
  3. Test in our Sandbox
  4. Go Live

Get Your API Keys

  1. Paysafe will provide you with the credentials in the Business Portal.
  2. Sign in to the Business Portal.
  3. To access your keys, from the left navigation bar, click Integrate > API Keys. You can find a new section that displays the Paysafe Payments API key that you need to use: The Private Key: used for all server-to-server API requests https://api.test.paysafe.com/paymenthub/v1

Making API Calls

Before you make your first API call, you will need to have some or all of the following information at hand:

  1. API endpoint – This is the URL to which you send your request, and its format depends on the type of API call.
  2. API key – You get your API Keys when you sign up with Paysafe. You must include it in the Authorization HTTPS header of most API requests. Refer to the section above (Get Your API Keys) for more information.
  3. Message body – This must be a valid JSON and contain valid Paysafe JSON objects, as required for the type of request. Not all API calls require a message body. For example, GET requests do not require a body.
  4. Resource ID – Some API calls require a resource ID in the API endpoint. For example, you may need this ID to refer to a resource created in one of the previous steps. 

Example

The code snippet below provides an example of the above credentials, included in a cURL request:

curl -X POST https://api.test.paysafe.com/paymenthub/v1/payments \

  -u 66040-1001062690:B-qa2-0-579b6aec-0-606c02147caae097f4392898ca08ae736e51d3093af388d90214528ac70b69c0359d3173d12480d07275ca54a7c7 \

  -H 'Content-Type: application/json'

Use the API request format as shown in the above example:

  • 66040-1001062690 – The number sequence before the colon is your username, to be included in the API endpoint.
  • B-qa2-0-579b6aec-0-… – The number sequence after the colon is your password.
  • The user name and password should be Base64 encoded before being included in your API request. You can do this manually or use a tool to automate this. For more information, see Authentication.

Troubleshooting API Requests

Below is a brief list of issues that can result in problems.

  • Not sending the request over HTTPS
  • Failure to include the correct authentication details (i.e., your API key) – a common error is adding spaces before or after the API key
  • Incorrect JSON syntax in the body of your request
  • Specifying the incorrect HTTP method – for most API requests this is POST, while requests for retrieving information from the Paysafe platform use GET

For further details, see the Troubleshooting section.

Payment Handle Overview

A Payment Handle represents the payment instrument details and the profile of a customer. Payment handle includes information such as credit card number, expiry date, the card holder’s name, the transaction type, billing address and profile information about a customer.

When you create a Payment Handle, Paysafe returns a paymentHandleToken in the response. This token contains all payment details of a customer that you must include in a payment request. You must create a separate Payment Handle for each transaction type. For example, if your transaction has a payment request and a standalone credit, you will be required to create separate payment handles for the payment and the standalone credit.

Payment Handles have a lifespan of 15 minutes and can be used only once. However, in some cases, for example, when you create a payment handle for a customer, the Payment Handle can be multi-use with an unlimited lifespan.

Important Parameters

Specifies what additional action you can take to complete a payment request. This is a read-only parameter. Paysafe returns it in the response of the Payment Handle creation request, regardless of the payment method selected by the customer.

The possible values are:

  • NONE – In this case, you can immediately make a Payment's call as the Payment Handle token is set to PAYABLE immediately.
  • REDIRECT – The customer is required to authorize the payment on a redirected page. This is typically the case with 3D Secure transactions, as they are redirected to a card provider’s 3D secure page for authenticating the transaction. You must redirect your customer to a link returned by Paysafe in the response. After successful authentication, the status of the Payment Handle token is set to PAYABLE.

You must make a payment request using the Payment Handle token immediately after the status of the Payment Handle token becomes PAYABLE. The life of the token is 15 minutes.

Specifies if you can use the paymentHandleToken once or multiple times. This is a read-only parameter. Paysafe returns it in the response to the Payment Handle creation request.

Payment Handle tokens are of two types – SINGLE_USE (regular Payment Handle token) and MULTI_USE (Customer Payment Handle token).

  • SINGLE_USE – The Payment Handle token can be used only once.
  • MULTI_USE – The Payment Handle token can be used multiple times. This could be used for recurring transactions like subscriptions or saved cards.

Specifies if the payment request will be completed immediately or with some delay. This is a read-only parameter. Paysafe returns this in the response to the Payment Handle creation request. You can use this information to determine if you want to receive the payment status synchronously or to rely on Webhooks.

The possible values are:

  • SYNCHRONOUS – Receive payment status synchronously. You can poll the PROCESSING/PENDING payments at regular intervals to retrieve the Payment status.
  • ASYNCHRONOUS – Receive payment status asynchronously. The payment is expected to be completed after a significant time delay. For example, the delay could span hours or days (as in the case of PaysafeCash). You can use webhooks to receive the payment status instantly in such cases.

Testing the API

The Paysafe Test environment can be used to test websites or applications without performing transactions through the Production (live) processing platform. Payment 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 test accounts of the Paysafe Payments API, you can:

  • Verify support for all the operation types that you require.
  • Review all common errors as well as errors that may occur for each operation.
  • Verify the lengths and format for all attributes you send
  • Specifying the incorrect HTTP method – for most API requests this is POST, while requests for retrieving information from the Paysafe platform use GET

For access to Test accounts and credentials, please contact your business relationship manager or reach out to integrations@paysafe.com. Your Test account will provide you with access to a Test version of the Paysafe Business Portal, where you can view the status of your Test transactions.

API endpoint: https://api.test.paysafe.com/paymenthub/v1

Go Live

Test accounts enable you to process API transactions that mirror the functionality in the Production environment. 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.

You have to use the following details to connect to each Paysafe Production environment.

  • API endpoint:https://api.paysafe.com/paymenthub/v1
  • Authentication credentials: Paysafe will provide you with the API Keys in the Business Portal.
  • You cannot use your Test credentials to process transaction requests in the Production environment.
On this Page