Skip to main content

​
What is a Hosted Payment Page?

A hosted payment page is a secure checkout page hosted by Revolv3. Instead of building your own payment form, you redirect customers to Revolv3’s page where they enter their payment details. Benefits:
  • ✅ No card data handling: You never see or handle sensitive payment information
  • ✅ PCI compliance: Revolv3 handles all PCI requirements
  • ✅ Quick integration: Just create a checkout session and redirect
  • ✅ Optimized UX: Payment forms are designed for conversion
  • ✅ Mobile-friendly: Works great on all devices
When to use it:
  • You want the fastest integration possible
  • You prefer not to handle payment forms
  • You want Revolv3 to manage the entire checkout experience
  • You’re okay with redirecting customers to a different URL

​
Prerequisites

Before you begin, make sure you have:
  1. ✅ Revolv3 account: Active merchant account with configured processors
  2. ✅ API key: Developer static token for authentication
  3. ✅ Trusted hostnames: Your website domain added to Trusted Checkout Hostnames in the portal

​
Step 1: Create a Checkout Session

Create a checkout session by sending a POST request to the checkout endpoint.

​
API Endpoint

POST {{Api Root}}/api/Checkout
Replace {{Api Root}} with:
  • Production: api.revolv3.com
  • Sandbox: api-sandbox.revolv3.com

​
Required Headers

Origin HTTP header requiredYou must include the Origin HTTP header in your request. This header should match one of your trusted hostnames.If the Origin header is missing or doesn’t match a trusted hostname, you’ll get a 400 Bad Request error.
Include these headers:
  • Origin: Your website’s origin (e.g., https://mysite.com)
  • x-revolv3-token: Your API key
  • Content-Type: application/json

​
Sample Request

{
  "ReturnUrl": "https://mysite.com/checkout/complete",
  "OneTimePayment": {
    "CheckoutLineItems": [
      {
        "Name": "Item 1",
        "Description": "Product description",
        "Value": 9.99,
        "ValueType": "Standard"
      },
      {
        "Name": "Item 2",
        "Description": "Another product",
        "Value": 21.99,
        "ValueType": "Standard"
      }
    ]
  }
}

​
Understanding the Request

FieldDescription
ReturnUrlImportant: Where to redirect the customer after payment. Must be URL-encoded and the hostname must be in your trusted hostnames list.
OneTimePayment.CheckoutLineItemsArray of items the customer is purchasing. Each item has a name, description, value, and value type.
ReturnUrl encoding: The ReturnUrl must be URL-encoded. For example:
  • Original: https://mysite.com/checkout/complete
  • Encoded: https%3A%2F%2Fmysite.com%2Fcheckout%2Fcomplete
ReturnUrl requirements:
  • Always include ReturnUrl: This is where customers return after payment
  • Hostname must be trusted: The hostname in ReturnUrl must be in your Trusted Checkout Hostnames list
  • URL encoding required: The URL must be encoded once (as shown in the example)
For details on line items and value types, see Checkout Line Items Value Types.

​
Response

When you create a checkout session, you’ll get back a checkout link: 
{
  "checkoutId": "0584773e-47bf-4822-91de-06acb5de9358",
  "checkoutLink": "https://portal.revolv3.com/checkout/0584773e-47bf-4822-91de-06acb5de9358"
}
Understanding the response:
  • checkoutId: Unique identifier for this checkout session (save this for tracking)
  • checkoutLink: The URL to redirect the customer to (this is Revolv3’s secure payment page)

​
Step 2: Redirect Customer to Checkout

Once you have the checkoutLink, redirect the customer to it:

​
JavaScript Example

// After creating checkout session
const response = await createCheckoutSession();
window.location.href = response.checkoutLink;  // Redirect customer

​
Server-Side Redirect Example

// Node.js/Express example
res.redirect(checkoutLink);

# Python/Flask example
return redirect(checkoutLink)

​
Step 3: Customer Completes Payment

  1. Customer is redirected to Revolv3’s secure payment page
  2. Customer enters payment details (card, billing address, etc.)
  3. Customer reviews order details
  4. Customer completes payment
  5. Customer is redirected back to your ReturnUrl

​
Step 4: Handle the Return

When the customer returns to your ReturnUrl, you can:
  1. Check checkout status: Use the checkout API to get the current status
  2. Show confirmation: Display a success or failure message
  3. Update order status: Mark the order as paid or failed in your system

​
Getting Checkout Status

Use the checkout ID to get the current status: 
GET {{Api Root}}/api/Checkout/{checkoutId}
Replace {checkoutId} with the ID from the checkout session response.

​
Referrer-Policy Header

Referrer-Policy HTTP headerTo ensure Revolv3 can verify that the customer was redirected from your authorized website, add a Referrer-Policy header with the value origin to your HTTP requests or HTML pages.In HTML, add this meta tag:
<meta name="referrer" content="origin" />
In HTTP requests, include the header:
Referrer-Policy: origin
This helps Revolv3 verify that checkout requests are coming from your authorized domain.

​
Real-World Example Flow

​
Complete Integration Example

1. Customer clicks “Checkout” on your site 2. Your backend creates checkout session: 
POST {{Api Root}}/api/Checkout
{
  "ReturnUrl": "https://mysite.com/checkout/complete",
  "OneTimePayment": {
    "CheckoutLineItems": [
      {
        "Name": "Premium Widget",
        "Value": 99.99,
        "ValueType": "Standard"
      }
    ]
  }
}
3. Backend receives checkout link: 
{
  "checkoutLink": "https://portal.revolv3.com/checkout/abc123"
}
4. Redirect customer: 
window.location.href = checkoutLink;
5. Customer completes payment on Revolv3’s page 6. Customer is redirected back to: 
https://mysite.com/checkout/complete
7. Your page checks status and shows confirmation

​
Best Practices

  1. Always set ReturnUrl: Customers need somewhere to return after payment
  2. URL encode ReturnUrl: Encode it properly before sending
  3. Store checkoutId: Save it so you can check status later
  4. Handle errors: Check checkout status when customer returns
  5. Test thoroughly: Test the full flow in sandbox before production

​
Common Questions

Q: What if the customer closes the payment page? A: The checkout session remains valid. You can check its status or create a new one if needed. Q: Can I customize the payment page? A: The hosted page uses Revolv3’s standard design. For more customization, consider embedded checkout. Q: How long is a checkout session valid? A: Checkout sessions typically expire after a period of inactivity. Check with Revolv3 support for specific timeout values. Q: Can I use this for subscriptions? A: Yes, checkout supports both one-time payments and subscriptions. See the API reference for subscription checkout options.

​
Next Steps