Dual Payment using XPay Token

Overview of the dual payment process where Cover Genius is the Merchant of Record

Partners that are at a minimum of PCI DSS SAQ A compliant are able to utilize the XPay API to process the insurance transaction. This will make Cover Genius the Merchant of Record (MoR) for the insurance portion of the transaction.

Overview

In a dual payment integration:

Partner collects payment for the main product/service
XCover (via XPay) collects payment for the insurance separately
Customer experiences two transactions in quick succession
Partner remains MoR for product, XCover is MoR for insurance

Workflow

Step 1: Create Offers

Request insurance product offerings using the Create Offers endpoint. Display the insurance products and pricing to the customer during the shopping experience.

Step 2: Collect Payment Details

After a customer selects the insurance product and proceeds to the checkout stage, the payment information (credit card details) must be collected and transmitted through the XPay Customer Tokens endpoint.

Sending Payment Details:

POST  /xpay/customer_tokens

The XPay API uses a long-lived JSON Web Token (JWT) which will be provided to you by the assigned Client Solutions Engineer (CSE).

Step 3: Process Main Product Payment

Process the payment for the main product/service through your own payment provider.

Step 4: Confirm Offer with XPay Details

Call the Confirm Offer endpoint with the XPay payment details:

{
  "quotes": [
    {
      "id": "quote-uuid-from-offer"
    }
  ],
  "policyholder": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone": "+1234567890",
    "country": "US"
  },
  "payment_details": {
    "provider": "xpay",
    "xpay_customer_id": "customer_token_from_step_2",
    "customer_token_id": "customer_token_from_step_2"
  }
}

Step 5: XPay Processes Insurance Payment

XPay will automatically process the insurance payment using the provided customer token. The insurance transaction will appear as a separate charge on the customer's payment method.

Authentication

The XPay API requires authentication using a JWT token:

Authorization: Bearer <your_xpay_jwt_token>

Your assigned CSE will provide you with the long-lived JWT token for XPay API access.

Important Notes

PCI Compliance: Partners must be at minimum PCI DSS SAQ A compliant to use XPay token-based payments.

Customer Experience: Inform customers that they will see two separate charges on their payment method - one for the main product and one for insurance.

Merchant of Record: Cover Genius is the merchant of record for the insurance transaction when using XPay.

Token Security: Store XPay JWT tokens securely and never expose them in client-side code.

Error Handling

If the XPay payment fails during the Confirm Offer request:

The response will include error details in the errors object
The booking will not be confirmed
You may need to retry with a different payment method or customer token
Inform the customer that the insurance payment failed and offer to retry

Testing

Use the XPay sandbox environment for testing:

Test JWT tokens will be provided by your CSE
Use test credit card numbers provided in the XPay documentation
Sandbox transactions will not result in actual charges

PreviousSingle Payment

NextRendering an Offer Panel

Last updated 17 days ago

Was this helpful?