> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revolv3.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Hosted Payment Page
> Learn how to use Revolv3's hosted checkout page. Redirect customers to a secure Revolv3 payment page without handling card data yourself.
## 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 required**
You **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
```bash bash theme={null}
{
"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
| Field | Description |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `ReturnUrl` | **Important**: Where to redirect the customer after payment. Must be URL-encoded and the hostname must be in your trusted hostnames list. |
| `OneTimePayment.CheckoutLineItems` | Array 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](/docs/checkout/checkout-line-items-value-types).
### Response
When you create a checkout session, you'll get back a checkout link:
```bash bash theme={null}
{
"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
```javascript theme={null}
// After creating checkout session
const response = await createCheckoutSession();
window.location.href = response.checkoutLink; // Redirect customer
```
### Server-Side Redirect Example
```javascript theme={null}
// Node.js/Express example
res.redirect(checkoutLink);
```
```python theme={null}
# 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 header**
To 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:
```html theme={null}
```
**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:**
```javascript theme={null}
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:**
```json theme={null}
{
"checkoutLink": "https://portal.revolv3.com/checkout/abc123"
}
```
**4. Redirect customer:**
```javascript theme={null}
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
* **[Embedded Checkout](/docs/checkout/embedded)** — Learn about embedding checkout in your site
* **[Checkout Line Items](/docs/checkout/checkout-line-items-value-types)** — Understand how to structure checkout items
* **[Checkout Overview](/docs/checkout)** — Return to checkout overview
***