HPP Integration Guide

curl -X POST https://api.cresoracommerce.com/api/v1/hpp/sessions \
  -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://api.cresoracommerce.com/api/v1/hpp/sessions",
    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()

const resp = await fetch("https://api.cresoracommerce.com/api/v1/hpp/sessions", {
  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();

{
  "session_id": "hpp_xxxxxxxxxxxx",
  "redirect_url": "https://pay.cresoracommerce.com/s/hpp_xxxxxxxxxxxx",
  "expires_at": "2026-05-29T10:10:00Z"
}

1. Your server creates an 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 a payment webhook
6. Your server verifies the webhook and fulfills the order

https://yourapp.com/checkout/complete?session_id=hpp_xxxx&status=captured

1. Register your domain in Partner Portal → Merchant Settings → HPP → Allowed Origins
2. Create an HPP session with parent_origin set to your page's exact HTTPS origin
3. Embed redirect_url in an <iframe> on your page
4. Load the Cresora HPP client library
5. Register event handlers for the postMessage lifecycle
6. Fulfill the order on payment_succeeded (backed by webhook verification)

<iframe
  id="payment-frame"
  src="https://pay.cresoracommerce.com/s/hpp_xxxxxxxxxxxx"
  style="width: 100%; border: none;"
></iframe>

<script src="https://pay.cresoracommerce.com/client/cresora-hpp-client.v1.js"></script>

<script>
  // Listen for lifecycle events from the HPP
  CреsoraHpp.on('ready', () => {
    // Form is mounted and interactive — safe to show your checkout UI
  });

  CреsoraHpp.on('payment_succeeded', (evt) => {
    console.log('Payment captured:', evt.data.transactionId);
    console.log('Amount:', evt.data.approvedAmount, 'Last 4:', evt.data.last4);
    closeCheckoutModal();
    // Still verify the webhook before fulfilling
  });

  CреsoraHpp.on('payment_failed', (evt) => {
    showError(evt.data.reason || 'Payment failed. Please try again.');
  });

  CреsoraHpp.on('height_changed', (evt) => {
    // Auto-resize the iframe to fit the form
    document.getElementById('payment-frame').style.height = evt.data.height + 'px';
  });

  CреsoraHpp.on('session_invalid', (evt) => {
    showError('Session expired. Please refresh and try again.');
  });

  // Cancel button — sends a cancel command back into the iframe
  document.getElementById('cancel-button').addEventListener('click', () => {
    CреsoraHpp.send(
      document.getElementById('payment-frame'),
      'cancel',
      null,
      sessionId
    );
  });

  // Fallback: if no event arrives within 5 seconds, treat as session_invalid
  const timeout = setTimeout(() => {
    showError('Unable to load payment form. Please try again.');
  }, 5000);
  CреsoraHpp.on('session_loaded', () => clearTimeout(timeout));
</script>

interface HppMessage {
  source: 'cresora-hpp';
  version: 1;
  sessionId: string;
  type: HppEventType;
  occurredAtUtc: string; // ISO-8601
  data?: object;         // shape varies by type
}

{
  transactionId: string,
  requestedAmount: number,
  approvedAmount: number,
  last4: string,
  brand: string,       // VISA, MASTERCARD, etc.
  authCode: string,
  responseMessage: string,
  status: string
}

window.addEventListener('message', (event) => {
  // 1. Validate origin — must be the Cresora HPP origin
  if (event.origin !== 'https://pay.cresoracommerce.com') return;

  const msg = event.data;

  // 2. Validate source discriminator
  if (!msg || msg.source !== 'cresora-hpp') return;

  // 3. Validate session scope — prevents cross-session bleed
  if (msg.sessionId !== mySessionId) return;

  // Safe to handle msg.type
});