HPP Integration Guide
Integrate the Cresora Hosted Payment Page for the lowest PCI scope (SAQ A).
The Hosted Payment Page (HPP) lets you accept payments without your server ever handling raw card data. Cresora renders and hosts the payment form; you redirect your customer to it and receive a webhook when the payment completes.
PCI scope: SAQ A — the lowest possible scope because no card data touches your systems.
Flow overview
1. Your server creates an HPP session via POST /v1/payments/hpp-session
2. Redirect the customer to session.redirect_url
3. Customer enters card details on the Cresora-hosted page
4. Cresora redirects back to your return_url
5. Cresora fires payment.captured webhook
6. Your server verifies the webhook and fulfills the orderCreate an HPP session
curl -X POST https://sandbox-api.cresoracommerce.com/api/v1/payments/hpp-session \
-H "Authorization: Bearer csk_test_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: idem_$(uuidgen)" \
-d '{
"merchant_id": "mrch_xxxxxxxxxx",
"amount": "50.00",
"currency": "USD",
"return_url": "https://yourapp.com/checkout/complete",
"cancel_url": "https://yourapp.com/checkout/cancel"
}'import requests, uuid
resp = requests.post(
"https://sandbox-api.cresoracommerce.com/api/v1/payments/hpp-session",
headers={
"Authorization": "Bearer csk_test_xxxxxxxxxxxx",
"Idempotency-Key": f"idem_{uuid.uuid4()}",
},
json={
"merchant_id": "mrch_xxxxxxxxxx",
"amount": "50.00",
"currency": "USD",
"return_url": "https://yourapp.com/checkout/complete",
"cancel_url": "https://yourapp.com/checkout/cancel",
},
)
session = resp.json()
# Redirect customer to session["redirect_url"]const resp = await fetch("https://sandbox-api.cresoracommerce.com/api/v1/payments/hpp-session", {
method: "POST",
headers: {
Authorization: "Bearer csk_test_xxxxxxxxxxxx",
"Content-Type": "application/json",
"Idempotency-Key": "idem_" + crypto.randomUUID(),
},
body: JSON.stringify({
merchant_id: "mrch_xxxxxxxxxx",
amount: "50.00",
currency: "USD",
return_url: "https://yourapp.com/checkout/complete",
cancel_url: "https://yourapp.com/checkout/cancel",
}),
});
const session = await resp.json();
// res.redirect(session.redirect_url);HPP session response
{
"session_id": "hpp_xxxxxxxxxxxx",
"redirect_url": "https://pay.cresoracommerce.com/s/hpp_xxxxxxxxxxxx",
"expires_at": "2026-05-29T10:30:00Z"
}HPP sessions expire after 30 minutes. Create a new session if the customer returns after expiry.
Handle the return
When the customer completes or cancels payment, Cresora redirects to your return_url with query params:
https://yourapp.com/checkout/complete?session_id=hpp_xxxx&status=capturedstatus | Meaning |
|---|---|
captured | Payment successful |
failed | Payment declined |
cancelled | Customer clicked cancel |
Do not trust the status query parameter alone to fulfill orders. Always wait for the payment.captured webhook and verify its signature. Query parameters can be spoofed.
White-label branding
Custom HPP branding (logo + primary color) requires the hpp_whitelabel feature flag. See API Reference (Preview) →.