Supported Functionality

---

Adding a Paysafe Merchant

To connect a Merchant using the Paysafe Gateway,

1. First add Merchant
2. Select Paysafe as the Gateway
3. Add Gateway Details as outlined below

*Required

MOTO (Mail Order/Telephone Order)

When Pass MOTO Payment Type is checked, Vrio will pass entryMode: MOTO on the payment handle request for initial transactions that do not have 3DS authentication data. This tells Paysafe the transaction is a mail order or telephone order and does not require 3D Secure authentication.

If 3DS authentication data is present on the order, it will take priority over the MOTO setting and the 3DS values will be passed instead.

Important

If you are using a third-party 3DS provider (e.g., Paay.co), do not check "Pass MOTO Payment Type" — the 3DS data from your provider will be passed automatically. Learn more about third-party 3DS integrations here.

---

Attempt 3D Secure

When Attempt 3D Secure is checked, Vrio will use Paysafe-managed 3D Secure authentication for initial transactions where the checkout supports redirects (i.e., a redirect_url is present).

How it works:

1. Vrio creates a payment handle with a threeDs object and returnLinks pointing back to the checkout.
2. If Paysafe determines a 3DS challenge is required, the payment handle returns with status: INITIATED and action: REDIRECT. Vrio returns a response_code: 101 with the redirect URL — the customer is redirected to complete 3DS authentication.
3. If the transaction is frictionless (no challenge needed), the payment handle returns as PAYABLE immediately and Vrio processes the payment in a single step — no redirect is needed.
4. After the customer completes 3DS authentication and is redirected back, the checkout calls the /order/{order_id}/complete endpoint. Vrio verifies the payment handle is now PAYABLE and processes the payment.

For handling the 101 response code, see Handling 101 Response Codes.

Priority

When both Attempt 3D Secure and Pass MOTO Payment Type are checked, 3D Secure takes priority for transactions where a redirect URL is present. For transactions without a redirect URL (e.g., API-initiated or recurring charges), the MOTO setting will be used as a fallback.

Paysafe Account Requirement

Paysafe-managed 3D Secure must be enabled on your Paysafe account. Contact Paysafe to enable this feature before checking this box. If it is not enabled, payment handle creation will fail with an authentication error.

---

Refunds

Paysafe does not support partial refunds on settlements that have not yet been batched. If a refund is attempted on an unbatched settlement and the refund amount equals the full settlement amount, Vrio will automatically attempt a settlement cancel instead. This is transparent to the user — the refund will appear successful.

If the refund amount is less than the full settlement amount and the settlement has not been batched, the refund will fail. In this case, wait for the settlement to batch before attempting the partial refund.

---

Request

Required Data Mapping

Below is a table that shows how Vrio maps its data to the Paysafe Payments API. Values in bold are hard coded values, the rest are dynamic based on the payment.

Payment Handle (New Card)

For new card transactions, Vrio first creates a payment handle to tokenize the card data before processing the payment.

Auth / Sale

---

Optional Data Mapping

3DS Variables (Third-Party Provider)

3DS values are passed on the payment handle request (not the payment request). They are only passed when 3DS authentication data exists on the order for the current cycle. This is used when you have a third-party 3DS provider (e.g., Paay.co or Payon) — not when using the Attempt 3D Secure checkbox.

Pay Attention

If using a third-party 3DS provider (e.g., Paay.co or Payon), do not check "Pass MOTO Payment Type" or "Attempt 3D Secure" on the merchant. The 3DS data from your provider will be passed automatically. Learn more about third-party 3DS integrations here.

3DS Variables (Paysafe-Managed)

When Attempt 3D Secure is checked and a redirect URL is present, the following data is passed on the payment handle request:

---

Stored Credentials (Recurring)

Vrio automatically passes stored credential data with every transaction to Paysafe.

---

Pass Merchant Descriptor

If Pass Merchant Descriptor is checked:

---

Card Tokenization

For new card transactions, after a successful payment, Vrio will automatically create a customer profile and store the card as a multi-use payment handle token for future transactions.

The resulting multi-use payment handle token is stored in the format: {paysafe_customer_id}|{multi_use_token}

For recurring charges, the stored multi-use token is used directly — no payment handle creation is needed, reducing the transaction to a single API call.

---

Response Data Mapping

Below is a table that shows how Vrio maps data from the Paysafe API response.

When a 101 response code is returned, the post_data field will contain the Paysafe 3DS redirect URL. The gateway_response_id will contain the payment handle ID, which is used to verify the handle status after the customer completes 3DS authentication.

---

Testing

Note : Placing test orders with a Paysafe sandbox account or using Paysafe test cards will not automatically set the order as a test in Vrio. Be sure to flag the order as a test using the is_test flag after the order is processed. For more details on placing test orders, click here.

For Paysafe test cards, check here.

---

FAQ

Q: I am getting a response_code=101 returned, what does that mean?

A: A response_code=101 indicates that 3D Secure authentication is required before the charge can be completed. The customer must be redirected to the URL in the post_data field to complete 3DS authentication. After authentication, use the /order/{order_id}/complete endpoint to finalize the transaction. Learn more here.

Q: My refund is failing on a recent transaction, what should I do?

A: Paysafe does not support partial refunds on settlements that have not yet been batched. Vrio will automatically attempt a settlement cancel for full refunds on unbatched settlements, but partial refunds will fail. Wait for the settlement to batch (typically the next business day) before attempting a partial refund.

Q: I have both "Pass MOTO Payment Type" and "Attempt 3D Secure" checked — which one takes priority?

A: When both are checked, 3D Secure takes priority for transactions where a redirect URL is present (e.g., checkout page transactions). For transactions without a redirect URL (e.g., API-initiated charges or recurring renewals), the MOTO setting will be used as a fallback.