Hosted Payment Pages (HPP) Learn how to redirect your customers to a hosted payment page

Workflow

  1. Initialize payment page
  2. Redirect customer
  3. Capture authorized transaction
HPP Flow

1. Payment Page Initialization

The first step is to initialize a new payment page for your sale. For this your server will have to make an RPC request to Payyo with details about the sale. In return Payyo will respond with a URL where you can redirect your customer to.

{
  "jsonrpc": "2.0",
  "method": "paymentPage.initialize",
  "params": {
    "merchant_id": 1,
    "merchant_reference": "10000002",
    "description": "Bungee jumping with a very, very secure rope",
    "currency": "USD",
    "amount": 20000,
    "billing_descriptor": "JOHN DOE LTD",
    "styling": {
      "favicon_url": "https://assets.payyo.ch/favicon/favicon-32x32.png",
      "primary_color": "rgba(255,255,255,1.0)",
      "accent_color": "rgba(255,0,0,1.0)",
      "background_color": "rgba(230,230,230,1.0)"
    },
    "return_urls": {
      "success": "https://www.example.com/success",
      "error": "https://www.example.com/error",
      "abort": "https://www.example.com/abort"
    },
    "language": "de"
  },
  "id": 1
}
{
  "jsonrpc": "2.0",
  "result": {
    "payment_page_id": "pp_2a6ca6d48540537fc6d8a71ec6fb",
    "checkout_url": "https://checkout.sandbox.payyo.ch/pp/pp_2a6ca6d48540537fc6d8a71ec6fb"
  },
  "id": 1
}

Reusability

By default payment pages are not reusable. This means a payment page cannot be re-opened and used to make multiple charges. To enable reusability the is_reusable property can be set to true.

If a customer re-opens an already used payment page they are redirected to the return_urls.success URL immediately. Please prepare your application to handle such cases appropriately.

{
  "jsonrpc": "2.0",
  "method": "paymentPage.initialize",
  "params": {
    ...
    "is_reusable": false
    ...
  },
  "id": 1
}

Expiration

By default payment pages do not expire and can be used at any point in the future. If you would like to require a customer to complete their payment within a certain time you can specify the expiration_time property. The value is the number of seconds until the payment page expires.

{
  "jsonrpc": "2.0",
  "method": "paymentPage.initialize",
  "params": {
    ...
    "expiration_time": 3600
    ...
  },
  "id": 1
}

In this example the payment page would expire after 1 hour. You can read more on this topic in the release notes about HPP expiration.

2. Customer Redirect

You can now redirect the customer to the checkout_url returned in the initialization response. The customer will return to one of the three URLs specified in the return_urls property.

  • success return: The payment was authorized. There will be a transaction_id property added to the URL you provided (https://www.example.com/success?transaction_id=... in the example). This transaction ID can be used to capture the amount immediately or over the next couple of days.
  • error return: Something went terribly wrong. You could try again or delay the sale.
  • abort return: The customer decided to abort the payment process.

3. Transaction capturing

Once you have received the transaction ID representing the authorized transaction you need to capture the transaction to finalize the sale.

{
  "jsonrpc": "2.0",
  "method": "transaction.capture",
  "params": {
    "transaction_id": "tra_..."
  },
  "id": 1
}
{
  "jsonrpc": "2.0",
  "result": {
    "transaction_id": "tra_...",
    "status": "settled"
  },
  "id": 1
}