Getting Started

Here's a step-by-step guide:

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

Get Your API Keys

Paysafe will provide you with the credentials in the Business Portal.

To access your keys, sign in to the Business Portal. You will find a new section that displays the Paysafe Payments API key that you need to use:

  1. 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. See Getting Your API Keys for more information. You must include it in the Authorization HTTPS header of most API requests.
  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.

Authentication Example

Structure of a Typical Payments API Request

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'

Please note the format to include in your API request as per 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 like the 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.

Some Important Parameters

A few additional parameters are important when creating a Payment Handle. These parameters may have an impact on how the created payment token (paymentHandleToken) is used. The following are the three parameters:

  • action
  • usage
  • executionMode

action

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 Payments 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.

usage

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.

executionMode

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 synchronously. 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 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 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.
Did you find this page useful?