Quick Start: Hosted Payment Page

#Prerequisites

• Sandbox credentials (merchantKey + merchantSecret) from Exirom
• A configured callback URL

#Step 1: Authenticate

curl -X POST https://sandbox.api.exirom.com/api/api/v1/auth \
  -H "Content-Type: application/json" \
  -d '{
    "merchantKey": "YOUR_MERCHANT_KEY",
    "merchantSecret": "YOUR_MERCHANT_SECRET"
  }'

{
  "merchantKey": "YOUR_MERCHANT_KEY",
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

#Step 2: Create a Payment Intent

curl -X POST https://sandbox.api.exirom.com/api/api/v1/payments/intent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "requestId": "unique-request-id-001",
    "mid": "YOUR_MID",
    "amount": "25.00",
    "currency": "EUR",
    "callbackUrl": "https://your-domain.com/callback",
    "successRedirectUrl": "https://your-domain.com/payment-complete",
    "failureRedirectUrl": "https://your-domain.com/payment-failed",
    "billingDetails": {
      "firstName": "Test",
      "lastName": "User",
      "email": "test@example.com",
      "country": "DE"
    },
    "order": {
      "orderId": "order-789",
      "title": "Premium subscription"
    },
    "device": {
      "ip": "203.0.113.1"
    }
  }'

{
  "transactionId": "txn_hpp_789",
  "redirectUrl": "https://checkout.exirom.com/pay/txn_hpp_789"
}

For full request/response schema, see POST /api/v1/payments/intent API Reference.

#Step 3: Redirect the Customer

Send the customer to the redirectUrl. Exirom's hosted page handles:

• Card input and validation
• APM method selection (if configured)
• 3D Secure challenges
• Localization and responsive design

After payment, the customer is redirected to your successRedirectUrl or failureRedirectUrl.

#Step 4: Receive the Result

Exirom sends a webhook POST to your callbackUrl:

{
  "transactionId": "txn_hpp_789",
  "transactionStatus": "SUCCEED",
  "amount": 25.00,
  "currency": "EUR",
  "paymentMethod": "CARD",
  "requestId": "unique-request-id-001"
}

The callback includes a paymentMethod query parameter indicating whether the customer paid by card or APM. See HPP Webhooks for details.

#Why Use HPP?

No PCI scope. Card data is entered directly on Exirom's hosted page and never touches your servers. This eliminates PCI DSS Level 1 certification requirements entirely — the most expensive and time-consuming compliance burden in payment processing.

One API, all payment methods. A single POST /api/v1/payments/intent call gives your customers access to cards and every APM enabled on your merchant account. No need to integrate each payment method separately.

Fastest time to market. Four API calls total (auth + create intent + handle redirect + receive callback). No card forms, no 3DS handling, no APM-specific logic.

Automatic 3D Secure. Exirom handles the full 3DS challenge flow — your backend never needs to manage redirects, iframes, or device fingerprinting.

#HPP Customization

For full UI branding (colors, logos, layouts), use the Cashier SDK (separate documentation).

#HPP vs Direct API

Not sure which to choose? See Choosing Your Integration for a detailed decision guide.

#What's Next?

• Payment Intents Guide — full request/response reference
• HPP Webhooks — parsing callback data
• Card Quick Start — direct card integration
• APM Quick Start — direct APM integration
• Integration Checklist — pre-go-live checklist