Paysafe Hosted Payments API Integration

• “Full redirect“, your customers will be transferred to a Paysafe hosted payment page which handles the collection of sensitive payment data and then they will be returned to your store.
• “Iframe” process will display the same Paysafe hosted payment page, but it will be displayed in an iframe within your online store, on the Pay page. This way your customers will never have to leave your store to pay for an order.

The gateway supports the following payment processes:

• Sale and Authorization Only payments
• WooCommerce Subscriptions product payments (requires separate plugin “WooCommerce Subscriptions“)
  • Important: WooCommerce Subscriptions version 2.0 and higher are supported only
• WooCommerce Pre-Orders product payments (requires separate plugin “WooCommerce Pre-Orders“)
• Process refunds directly from the Edit Order screen.
• Capture payments directly from the Edit Order screen.

Installation

↑ Back to top

1. Download the .zip file from your WooCommerce account.
2. Go to: WordPress Admin > Plugins > Add New and Upload Plugin with the file you downloaded with Choose File.
3. Install Now and Activate the extension.

More information at Install and Activate Plugins/Extensions.

Setup and Configuration

↑ Back to top

To set up your Paysafe integration in a few steps:

1. Log in to your WooCommerce store.
2. Go to: WooCommerce > Settings > Payments > Paysafe Hosted Payments API.
3. Enter Method Title and Method Description
4. Enter your API Key User Name and API Key Password
5. Leave everything else as default.
6. Start accepting payments

Recommended: Make a few test payments before you go live. In Live mode make a couple of small test payments, too.

Settings

↑ Back to top

Settings are broken into sections, and every section controls part of the integration.

Integration Type Section

↑ Back to top

This section is used to choose from the integration types the plugin offers. Currently, we offer two integration types and if you are reading the Hosted Payments API documentation page, then you likely chose the Hosted Payments API integration type. Here is how an integration type selection works:

1. Choose one of the options from the Integration Type selection setting
2. After you change your selection you will see a notice under it prompting you to save the change before you continue.
3. Click the “Save changes” button, and the page will refresh. You are ready to set up your gateway.

General Section

↑ Back to top

• Method Title:
  • This controls the title which the user sees during checkout. Also, it is displayed whenever the gateway is referenced.
• Description:
  • This controls the description which the user sees during checkout.

Credentials Section

↑ Back to top

• API Key: User Name:
  • This is the API Key User Name found in your Paysafe Dashboard > Settings > API Key.
• API Key: Password:
  • This is the API Key Password found in your Paysafe Dashboard > Settings > API Key.
  • Note: The Password will not appear in the text field, but a placeholder will let you know if it is set or not.

Transaction Settings Section

↑ Back to top

• Payment Pages Language:
  • Controls the language of the Paysafe payment page. You can choose from four languages British English, US English, French and French Canadian.
• Authorization Type:
  • “Authorization and Capture“, will capture the funds at the same time.
  • “Authorization Only“, will only perform authorization and let you capture the funds at a later date.
• Send Order Details:
  • Enable, if you want to send a breakdown of all order details (items, taxes, shipping costs) to Paysafe.
    Note: When sending the order details we break the order into its parts and send each part total to Paysafe. Paysafe then sums all parts and compares it to the order grand total. There are cases where the two totals do not match by a cent or two. In those cases, the transaction will be refused by Paysafe. We recommend disabling this option if you see errors.
  • Disable, if you want to just send the Order Total for the customer to pay.
• Send Customer IP:
  • This option will allow the plugin to send the customer IP with the payment request.
• Synchronous responses:
  • Enable, payment response will be made synchronously, in-line with the customer returning to your store.
  • Disable, payment responses will be made asynchronously, will be delayed a bit, allowing the callback system can detect problems with the merchant system and retry any failed attempts until a successful response is received.
  • Recommended from Paysafe: Disable.
• Customer ID Prefix:
  • The customer prefix ensures that there won’t be any customer duplicates between merchant stores. If you operate multiple stores, the prefix will be the one that differentiates between stored.
• Merchant Notification Email
  • If you want to receive email payment notifications, you should enter an email here. Paysafe will send you an email, whenever you receive a payment. Note: This setting does not automatically enable the dispatch of merchant notification emails, it tells Paysafe where to send the emails to. To enable the email notifications, please contact Paysafe for help.
• Accepted Cards
  • This setting will allow you to easily display your accepted payment methods on the checkout page payment option. It will not control the actual payment cards accepted on the Paysafe payment page, it is just an easy way to show the correct card icons on the checkout page.

Iframe Settings

↑ Back to top

To set up Iframe:

• Enable Iframe:
  • When enabled, the payment form will be displayed in an iframe on your store, instead of directing the customers to an off-site payment form page.
• Iframe Width:
  • The width of the iframe window. Enter only numbers in pixels (i.e. 700) or you can enter a number in percentage but you need to suffix it with “%” (i.e. 55%).
• Iframe Height:
  • The height of the iframe window. Entered can be a number in pixels (i.e. 850) or you can enter a number in percentage but you need to suffix it with “%” (i.e. 55%).
• Iframe Scroll:
  • Should the iframe be scrollable or not. If scrollable, the customer will be able to scroll to the iframe to reach its borders.

Reset Payment Profiles

↑ Back to top

In the rear events where you switch Paysafe accounts be it from a test account or just switching accounts, you might get a payment profile error whenever you attempt a payment. For this, we built a Payment Profile reset process, which resets all payment profiles and allows the store to continue to accept payments with the new account. To reset profiles:

1. Go to the plugin settings and scroll down to the “Reset Customer Profiles” section
2. Check the checkbox “Show Reset Profiles”
3. Click the “Reset Profiles” button. 

Process Refunds

↑ Back to top

To process a refund through the plugin:

1. Go to the “Order Edit” screen
2. Under “Items” meta box, in the bottom left corner, you will see a “Refund” button. Click it.
3. Enter the amount you want to refund. You can also enter a refund reason.
4. Press the “Refund … via Paysafe” button
5. The refund will be processed and upon page refresh you will see an order note, noting the refund amount, reason and transaction ID.

Capture Payments

↑ Back to top

To capture previously authorized payments:

1. Go to the “Order Edit” screen
2. Under “Items” meta box, in the bottom left corner, you will see a “Capture” button. Click it to expose the capture input fields.
3. Enter the amount you want to capture from the order. Note: you will see how much is authorized, you can’t capture more than that amount.
4. Press Capture Payment button.
5. A note will be left on the order with details about the captured amount and the transaction ID from the process.

Actions and Filters

↑ Back to top

Actions

↑ Back to top

‘wc_paysafe_payment_response_processed‘ ($order, $response) – Allow the merchant to perform any actions after the order is processed and before the user is redirected to the “Thank You” page. ‘wc_paysafe_redirect_hosted_refund_response_processed‘ – ($response, $response_processor_object, $order) – Allows actions after a refund response is processed ‘wc_paysafe_redirect_hosted_addons_response_processed‘ – ($response, $response_processor_object, $order) – Allows actions after a subscription\pre-order payment is processed ‘wc_paysafe_redirect_hosted_response_processed‘ – ($response, $response_processor_object, $order) – Allows actions after a regular product payment is processed ‘wc_paysafe_redirect_hosted_successful_response_processed‘ – ($response, $response_processor_object, $order) – Allows actions after successful payment response is processed ‘wc_paysafe_redirect_hosted_abandoned_response_processed‘ – ($response, $response_processor_object, $order) – Allows actions after abandoned payment response is processed ‘wc_paysafe_redirect_hosted_declined_response_processed‘ – ($response, $response_processor_object, $order) – Allows actions after declined payment response is processed ‘wc_paysafe_redirect_hosted_cancelled_response_processed‘ – ($response, $response_processor_object, $order) – Allows actions after cancelled payment response is processed

Filters

↑ Back to top

‘paysafe_restricted_characters‘ ($characters_array) – Those characters are stripped from the request. can be used to add to those characters. ‘wc_paysafe_allowed_order_status_to_save_profile‘ – ($statuses_array) – The order statuses will allow the Nebtanx profile to be saved to the order. ‘woocommerce_paysafe_icon‘ ($icon_url) – accepts the gateway default icon/image. ‘wc_paysafe_filter_api_key‘ – ($api_key_string) –  This filter allows the merchant to change the API key used for the payment request. ‘wc_paysafe_addons_request_params‘ ($request_parameters, $order) – Allows for manipulation of the payment request. ‘wc_paysafe_request_params‘ – ($request_parameters, $order) – Allows for manipulation of the payment request. ‘wc_paysafe_subscription_rebill_parameters‘ ($params, $order, $gateway) – Allows to modify the Subscriptions Scheduled payment request parameters ‘wc_paysafe_locale‘ – ($locale_string) – Allows for the locale to be changed run-time. ‘wc_paysafe_settlement_parameters‘ – ($params, $order, $amount, $gateway) – Allows to modify the capture request parameters ‘wc_paysafe_payment_customer_redirect_url‘ – ($url, $status_string, $order_id) – Allows the merchant to manipulate the customer final redirection location, like custom, Thank You page or just add URL parameters to track some behavior. ‘wc_paysafe_redirect_hosted_message_above_iframe‘ – ($message_string) – Allows to display a different message above the payment iframe

FAQ & Troubleshooting

↑ Back to top

Payment attempts fail with the error “Invalid customerIp”, what can I do?

↑ Back to top

Use this PHP snippet to remove the IP from the payment requests: Add the snippet anywhere in your ‘themes[theme-name]\functions.php‘ file.

I have a Paysafe account that allows the use of multiple merchant accounts, how can I use the different merchant accounts based on the order currency?

↑ Back to top

When you have one Paysafe account with multiple merchant accounts in it, it allows you to use different merchant accounts for different currencies. All you need to do is send the merchant account authorized to charge the correct currency with the payment request. Here is a snippet to send the merchant account based on the order currency: Add the snippet anywhere in your ‘themes[theme-name]\functions.php‘ file.

I switched from Live to Test Paysafe merchant account and now my transaction attempts fail with “Error message: The ID(s) specified in the URL do not correspond to the values in the system.: 717b26f5-7e90-sl4i-10xe-7e9ada0cac7f “, what should I do?

↑ Back to top

The gateway plugin uses Paysafe Vault profiles to manage customer payment profiles, when you switch merchant accounts (or just switch from Live to test merchant account) the profiles generated for the old merchant account are still in use and the Paysafe system will not recognize them for the new account. You have two options:

• If you want to test a single transaction to make sure everything works, just create a new user and process a transaction. A new profile will be created with the new merchant account and everything should be fine.
• If you are switching to the new merchant account you should reset the customer profiles as well. To reset the customer profiles just follow the “Reset Payment Profiles” guide above.

Questions & Support

↑ Back to top

Have a question before you buy? Please fill out this pre-sales form. Already purchased and need some assistance? Get in touch the developer via the Help Desk.