Skip to main content

Hosted Checkout (HPP)

The Hosted Payment Page (HPP) provides a ready-to-use checkout experience. Redirect your customers to a WickiePay-hosted page where they can complete their payment.

Why Use Hosted Checkout?​

  • No frontend work — WickiePay handles the payment UI
  • Mobile-optimized — Responsive design for all devices
  • Multi-currency — Customer selects their preferred crypto
  • QR Code — Built-in QR code for mobile wallet scanning
  • Real-time updates — Live status updates on the payment page

Integration Flow​

1. Your server: POST /api/v1/pay/summary → receive redirectUrl
2. Redirect customer to redirectUrl
3. Customer selects crypto and pays
4. Customer redirected to your returnUrl
5. Your server receives webhook notification

Step 1: Create Payment​

POST /api/v1/pay/summary
Content-Type: application/json

{
  "merchantId": "your-merchant-id",
  "type": "IN",
  "amount": 99.99,
  "currency": "EUR",
  "reference": "checkout-12345",
  "expiryMinutes": 30,
  "returnUrl": "https://yourshop.com/order/12345/confirm"
}

Step 2: Redirect Customer​

Use the redirectUrl from the response:

// Express.js example
app.post('/checkout', async (req, res) => {
  const payment = await createPayment({
    merchantId: process.env.MERCHANT_ID,
    type: 'IN',
    amount: req.body.total,
    currency: 'EUR',
    reference: req.body.orderId,
    returnUrl: `${process.env.BASE_URL}/order/${req.body.orderId}/confirm`
  });

  res.redirect(payment.redirectUrl);
});

Step 3: Handle Return​

When the customer completes (or cancels) the payment, they are redirected to your returnUrl with query parameters:

https://yourshop.com/order/12345/confirm?uuid=payment-uuid&status=COMPLETE
Don't Trust Client-Side Status

Always verify the payment status via API or webhook. The status query parameter is for display purposes only.

Step 4: Webhook Confirmation​

Set up a Webhook Listener to receive server-to-server confirmation:

{
  "event": "payment.completed",
  "data": {
    "uuid": "payment-uuid",
    "status": "COMPLETE",
    "reference": "checkout-12345",
    "amount": 99.99,
    "currency": "EUR"
  }
}

Customization​

The HPP displays your merchant branding:

  • Logo — Configured in Merchant Settings
  • Display Name — Shown on the payment page
  • Supported Currencies — Configurable per channel
Full API Access

All information displayed on the HPP is also available via the API response, allowing you to build a completely custom checkout experience if needed.

Handling Exceptions​

ScenarioBehavior
Customer underpaysHPP shows remaining amount, waits for additional payment
Payment expiresHPP shows expiration message, customer redirected
Network congestionHPP shows processing status with confirmation count
Customer cancelsCustomer redirected to returnUrl with status=CANCELLED

See Payment In — Handling Underpayments for API-level exception handling.

Next Steps​