Get Started

Before you make any server-to-server API calls, you need a private API key to authenticate with Paysafe. 

To get private API keys: 

1. Log in to the Paysafe Business Portal.

2. Go to Developer > API Keys.

3. Under Secret Key, click Authenticate Now.

4. Enter your Business Portal password and click Confirm.

5. You’ll now see your Username and Password.

API key is constructed as follows:

1. Combine the username and password into a string separated by a colon, for example, Username:Password.
2. The resulting string literal is then encoded using Base64.

For example:

• Username: MerchantXYZKey

• Password: B-tst1-0-51ed39e4-312d02345d3f123120881dff9bb4020a89e8ac44cdfdcecd702151182fdc952272661d290ab2e5849e31bb03deede7e

Key is formed by base64 encoding. 

MerchantXYZKey:B-tst1-0-51ed39e4-312d02345d3f123120881dff9bb4020a89e8ac44cdfdcecd702151182fdc952272661d290ab2e5849e31bb03deede7e

Base64-encoded API key: TWVyY2hhbnRYWVpLZXk6Qi10c3QxLTAtNTFlZDM5ZTQtMzEyZDAyMzQ1ZDNmMTIzMTIwODgxZGZmOWJiNDAyMGE4OWU4YWM0NGNkZmRjZWNkNzAyMTUxMTgyZmRjOTUyMjcyNjYxZDI5MGFiMmU1ODQ5ZTMxYmIwM2RlZWRlN2U=

A Payment Handle is a token that represents the customer’s payment and profile details. It includes information such as:

• Card number

• Alternative payment method details

• Billing address

• Customer profile

How It Works

1. Frontend Collection:
   • Securely collect payment/profile details using your hosted fields. 
2. Token Generation:
   • The collected information is sent to Paysafe, which returns a paymentHandleToken.
3. Transaction Processing:
   • Use this token to complete the transaction.

Paysafe supports two types of Payment Handles:

1. Single-Use Payment Handle

• Time to Live: Typically 15 minutes. 
• Usage: One-time use only. 
• Use Case: Typical for immediate, single transactions. 

2. Multi-Use payment handle

• Time to Live: Unlimited.

• Usage: Can be reused for multiple transactions. 

• Use Case: For recurring payments. 

• Available for Payment Methods: Cards, PaysafeCash, BACS, SEPA. 

State Transitions 

Payment handles transition through the above states based on actions taken and responses received during the transaction process. By understanding these statuses and transitions, you can effectively manage the lifecycle of a payment handle and ensure a smooth transaction process for your consumers. 

Single-use Payment Handle

• Single-use payment handles transition through various states like INITIATED, PAYABLE, COMPLETED, EXPIRED, FAILED, and CANCELLED. 

Multi-use Payment Handle

Webhooks and GET calls

• Webhooks: They notify your system of changes in the payment handle status. 

• GET calls: You can also pull the payment handle status using GET calls, however, it is recommended to use webhooks for real-time updates instead of polling using GET calls. 

The Payment Handle response includes important attributes that guide the payment process. Below are some attributes which are crucial for understanding how to proceed with the payment and ensuring that the integration handles the payment process correctly.

Actions

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

• NONE: You can immediately make a payment call as the payment handle token is set to PAYABLE immediately.
• REDIRECT: The customer is required to authorize the payment on a redirected page, typically for 3D Secure transactions. 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 it becomes PAYABLE. The token is valid for 15 minutes.

Token Types

• SINGLE_USE: The payment handle token can be used only once.
• MULTI_USE: The payment handle token can be used multiple times, suitable for recurring transactions like subscriptions or saved cards.

Execution Modes

Specifies if the payment request will be completed immediately or with some delay. This is a read-only parameter returned by Paysafe in the response to the payment handle creation request.

• 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, which could span hours or days (e.g., PaysafeCash). You can use webhooks to receive the payment status instantly in such cases.

You can process different transaction types such as Payment, Payout, Settlement, Refund, Cancel Payment and more using APIs. 

Paysafe supports two distinct environments for API integration:

• Test Environment: Used for development and testing. Transactions are simulated and do not involve real funds.

• Production Environment: Used for processing live transactions in a real-world setting.

Ensure you are using the appropriate environment and credentials based on your stage of development or deployment.

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

• API Endpoint: This is the URL to which you send your request, and its format depends on the type of API call.
• 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.
• 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.
• 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 1001062690:B-qa2-0-579b6aec-0-606c02147caae097f4392898ca08ae736e51d3093af388d90214528ac70b69c0359d3173d12480d07275ca54a7c7 \ -H 'Content-Type: application/json'

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

• 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 username 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.

The Paysafe Test Environment allows you to test your website or application without initiating real transactions through the live (production) platform. Transactions in this environment are processed using a simulator, which returns either a successful (approved) or failed (declined) response based on the parameters submitted in the API request.

Using the Paysafe Payments API test accounts, you can:

• Verify support for all required operation types.

• Review common errors as well as those specific to each operation.

• Confirm the length and format of all submitted attributes.

• Ensure correct use of HTTP methods (most API requests use POST, while GET is used for retrieving information).

To request test account access and credentials, contact your Business Relationship Manager or email integrations@paysafe.com. Test accounts also provide access to the Paysafe Business Portal - Test version, where you can monitor and review your test transactions.

• Test API Endpoint: https://api.test.paysafe.com/paymenthub/v1

The test environment mirrors the functionality of the production environment, enabling you to fully validate your integration before going live. Once testing is complete, replicate the same configuration changes in your production account.

To connect to the Paysafe production environment, use the following details:

• Production environment API Endpoint: https://api.paysafe.com/paymenthub/v1

• Authentication: API Keys will be provided in your Paysafe Business Portal.