HPP: Full Reference¶

Our HPP reference is here to help you find those hard-to-find bits of information all in one place. Use the navigation on the right to find your way around the page.

Redirecting customers to HPP¶

You can use a Payment Link (standard HTML form) or Payment Widget (JS) to collect and pass payment and customer details to HPP. More about integration methods you could find here.

When the customer selects the payment option, your website should post the HTML form containing their transaction details to: https://com.paycore.io/hpp/.

The HTML form should contain the mandatory hidden input fields listed in Configuration.

You could use a secure method of obtaining a precreated Payment Invoice ID before redirecting customers to HPP, as described in Secure redirection method.

Secure redirection method¶

This method can be used to ensure that details of the payment are communicated securely between your server and Corefy.

The redirection process is as follows:

1. Your web server makes a standard POST request with the payment parameters, using the Commerce Private API.
2. The Corefy server prepares a Payment Invoice for the payment and returns a standard HTTP(S) response with it.
3. Your web server takes the body of the response which contains a Payment Invoice ID value.
4. Using this Payment Invoice ID value the customer can be redirected to:

https://com.paycore.io/hpp/?cpi=<PAYMENT_INVOICE_ID>

<script async src="https://unpkg.com/@paycore/[email protected]/dist/paymentWidget.umd.min.js"></script>
<script>
window.payment_widget.init({
    cpi: "<PAYMENT_INVOICE_ID>",
});
</script>
<div id="payment_widget" style="width: 375px; height: 600px;"></div>

Configuration options¶

This is a complete list of HPP configuration options.

Your integration type decides how you set your parameters.

Basic¶

All following fields are required:

<script async src="https://unpkg.com/@paycore/[email protected]/dist/paymentWidget.umd.min.js"></script>
<script>
window.HPPConfig = {
    public_key: "<your_public_key>",
    amount: 100.00,
    currency: "USD"
};
</script>
<div id="payment_widget" style="width: 375px; height: 600px;"></div>

<form action="https://com.paycore.io/hpp/" method="get">
    <input type="hidden" name="public_key" value="<your_public_key>" />
    <input type="hidden" name="currency" value="USD" />
    <input type="hidden" name="amount" value="100" />
    <input type="submit" value="Pay" />
</form>

Optional¶

Optional values allow the user to more flexibly configure the HPP and add more information about payment invoice. For example, specify the validity period of payment invoice.

<script async src="https://unpkg.com/@paycore/[email protected]/dist/paymentWidget.umd.min.js"></script>
<script>
window.HPPConfig = {
    public_key: "<your_public_key>",
    amount: 100.00,
    currency: "USD",
    reference_id: "<your_unique_reference_id>",
    description: "Some goods",
    expires: 1602414000
};
</script>
<div id="payment_widget" style="width: 375px; height: 600px;"></div>

<form action="https://com.paycore.io/hpp/" method="get">
    <input type="hidden" name="public_key" value="<your_public_key>" />
    <input type="hidden" name="currency" value="USD" />
    <input type="hidden" name="amount" value="100" />
    <input type="hidden" name="reference_id" value="<your_unique_reference_id>" />
    <input type="hidden" name="description" value="Some goods" />
    <input type="hidden" name="expires" value="1602414000" />
    <input type="submit" value="Pay" />
</form>

Customer details¶

The customer element contains more information about the customer making the payment.

It includes customer[email], which we can use to send an email to the shopper when the payment is authorised or refused (if you choose to enable this notification channel).

Set in customer key a customer object with following optional properties:

<script async src="https://unpkg.com/@paycore/[email protected]/dist/paymentWidget.umd.min.js"></script>
<script>
window.HPPConfig = {
    public_key: "<your_public_key>",
    reference_id: "<your_unique_reference_id>",
    amount: 100.00,
    currency: "USD",
    description: "Some goods",
    customer: {
        reference_id: "cus_1234567",
        email: "[email protected]",
        name: "John Wick",
        metadata: {
            key1: "value1",
            key2: "value2"
        }
    }
};
</script>
<div id="payment_widget" style="width: 375px; height: 600px;"></div>

<form action="https://com.paycore.io/hpp/" method="get">
    <input type="hidden" name="public_key" value="<your_public_key>" />
    <input type="hidden" name="reference_id" value="<your_unique_reference_id>" />
    <input type="hidden" name="currency" value="USD" />
    <input type="hidden" name="amount" value="100" />
    <input type="hidden" name="description" value="Some goods" />
    <input type="hidden" name="customer[reference_id]" value="cus_1234567" />
    <input type="hidden" name="customer[email]" value="[email protected]" />
    <input type="hidden" name="customer[name]" value="John Wick" />
    <input type="hidden" name="customer[metadata][key1]" value="value1" />
    <input type="hidden" name="customer[metadata][key1]" value="value2" />
    <input type="submit" value="Pay" />
</form>

Auto process¶

The service and the service_fields fields are used to take the customer directly to a specific payment service gateway. Example: service: paypal_usd_hpp.

If the service has mandatory fields, the you need also specify them in service_fields field.

<script async src="https://unpkg.com/@paycore/[email protected]/dist/paymentWidget.umd.min.js"></script>
<script>
window.HPPConfig = {
    public_key: "<your_public_key>",
    amount: 100.00,
    currency: "USD",
    service: "paypal_usd_hpp"
};
</script>
<div id="payment_widget" style="width: 375px; height: 600px;"></div>

<form action="https://com.paycore.io/hpp/" method="get">
    <input type="hidden" name="public_key" value="<your_public_key>" />
    <input type="hidden" name="currency" value="USD" />
    <input type="hidden" name="amount" value="100" />
    <input type="hidden" name="service" value="paypal_usd_hpp" />
    <input type="submit" value="Pay" />
</form>

Return URL¶

Provide custom return_url so that your shoppers are returned to your website at the end of the payment process.

If return_url are not provided, shoppers are redirected to one of Corefy's default result pages, where the payment journey ends.

You could override the return URL on individual transactions in options key a options object with following optional properties:

With Auto return turned on in your Commerce account, you can set the value of the return_url variable on individual transactions, which overrides the value of the return URL stored in your Commerce account settings.

For example, you might want to redirect payers to a URL on your site that is specific to that person, perhaps with a session-id or other transaction-related data included in the URL.

To set the return URL for individual transactions, include the return_url variable in the payment invoice configuration.

<script async src="https://unpkg.com/@paycore/[email protected]/dist/paymentWidget.umd.min.js"></script>
<script>
window.HPPConfig = {
    public_key: "<your_public_key>",
    return_url: "https://somedomain.com/",
    amount: 100.00,
    currency: "USD",
    description: "Some goods"
};
</script>
<div id="payment_widget" style="width: 375px; height: 600px;"></div>

<form action="https://com.paycore.io/hpp/" method="get">
    <input type="hidden" name="public_key" value="<your_public_key>" />
    <input type="hidden" name="return_url" value="https://somedomain.com/" />
    <input type="hidden" name="currency" value="USD" />
    <input type="hidden" name="amount" value="100" />
    <input type="hidden" name="description" value="Some goods" />
    <input type="submit" value="Pay" />
</form>

Auto return the buyer to your website¶

With Auto return for Corefy payments, buyers are not required to click a button to return to your website after they complete their payments with Corefy. Auto Return applies to all Corefy Payments Standards payment buttons, including Buy Now, Shopping Cart, Subscription, and Donate buttons.

Auto Return shortens the checkout flow and immediately brings your buyers back to your website upon payment completion. To set up Auto Return, you need to turn it on in your Corefy account profile and enter the return URL that will be used to redirect your buyers back to your site. For more information on how to enable this feature in your Corefy account, see Auto return in the Commerce Account setup and administration guide.

Localization¶

HPP supports following languages in multiple regions around the world: English, Ukraininan, Russian.

<script async src="https://unpkg.com/@paycore/[email protected]/dist/paymentWidget.umd.min.js"></script>
<script>
window.HPPConfig = {
    public_key: "<your_public_key>",
    locale: "uk",
    amount: 100.00,
    currency: "USD",
    description: "Some goods"
};
</script>
<div id="payment_widget" style="width: 375px; height: 600px;"></div>

<form action="https://com.paycore.io/hpp/" method="get">
    <input type="hidden" name="public_key" value="<your_public_key>" />
    <input type="hidden" name="locale" value="uk" />
    <input type="hidden" name="currency" value="USD" />
    <input type="hidden" name="amount" value="100" />
    <input type="hidden" name="description" value="Some goods" />
    <input type="submit" value="Pay" />
</form>

Customization¶

One of our favorite things about HPP is its customizability. By following this styling guide, you can make changes to just about anything.

Display¶

Language and HPP layout settings.

Set in display key as an array object with the following properties:

Filtering¶

For some payment requests, you may decide to filter the payment methods that are displayed on the HPP or bypass the HPP entirely.

Set in display key as an array object with the following properties:

Styling¶

HPP can be customized to fit seamlessly with your brand. All customizations are achieved using selectors, properties and values in a manner very familiar to developers.

You can define advanced styling and customization of HPP by setting the styling property style in the configuration object.

The available options for the styling object:

Use the tabs below to view an example of styling, and a reference of selectors to use when styling your version of HPP.

payment_widget.init({
public_key: "YOUR_COMMERCE_ACCOUNT_PUBLIC_KEY",
amount: "100.00",
currency: "USD",
style: {
    pay_button_label: "pay",
    },
});

Metadata¶

Configuration property:

In the example above we suppose you will store the reference_id that’s unique to the payment in your order table. This way your website is able to look-up the order for this payment when the callback is sended by Corefy. Your website is keeping track of the payment, effectively bringing about the connection between order and payment. This approach is easiest to grasp, which is why we use it in our example.

Alternatively you could ask Corefy to remember the unique identifier of your order by instructing the Corefy API to store it in the payment’s metadata. You would provide it while creating the payment. In our example order_id would be a good candidate. Corefy stores the metadata for you, when you fetch the payment during processing the callback the metadata is included in the response. This is another way to connect orders and payments. We advise to use the metadata approach. This is the most popular approach and it’s easiest to implement.

If you want to store additional/custom data at a resource's level, you can make use of Corefy's Metadata.

For example, if you're a data service provider and want to store certain features of a particular plan, say "Usage Limit", "Speed within limit", etc., you can store it in the Metadata of the Plan.

Considering the same example as above, if you want to store the additional features of a particular data plan here's what the JSON will look like:

<script async src="https://unpkg.com/@paycore/[email protected]/dist/paymentWidget.umd.min.js"></script>
<script>
window.HPPConfig = {
    public_key: "<your_public_key>",
    reference_id: "<your_unique_reference_id>",
    amount: 100.00,
    currency: "USD",
    description: "Some goods",
    metadata: {
        "usage-limit": "5GB",
        "speed-within-quota": "2MBbps",
        "post-usage-quota": "512kbps"
    }
};
</script>
<div id="payment_widget" style="width: 375px; height: 600px;"></div>

<form action="https://com.paycore.io/hpp/" method="get">
    <input type="hidden" name="public_key" value="<your_public_key>" />
    <input type="hidden" name="reference_id" value="<your_unique_reference_id>" />
    <input type="hidden" name="currency" value="USD" />
    <input type="hidden" name="description" value="Some goods" />
    <input type="hidden" name="amount" value="100" />
    <input type="hidden" name="metadata[usage-limit]" value="5GB" />
    <input type="hidden" name="metadata[speed-within-quota]" value="2MBbps" />
    <input type="hidden" name="metadata[post-usage-quota]" value="512kbps" />
    <input type="submit" value="Pay" />
</form>

Embed options¶

We provide two ways to integrate:

• Full-page redirect: Redirect to a customizable hosted payment page.
• Embedded (iframe or lightbox): Display an overlay payment form on your site.

Full-page redirect¶

The Hosted Payment Page are displayed full-page in a browser. When your customers are redirected to the Hosted Payment Page, the web address for the Hosted Payment Page is displayed. Full-page redirect supports over 60 payment methods.

Set target field to redirect for Payment Widget integration method.

<script async src="https://unpkg.com/@paycore/[email protected]/dist/paymentWidget.umd.min.js"></script>
<script>
window.HPPConfig = {
    public_key: "<your_public_key>",
    amount: 100.00,
    currency: "USD",
    description: "Some goods",
    target: "redirect"
};
</script>

<form action="https://com.paycore.io/hpp/" method="get" target="_self">
    <input type="hidden" name="public_key" value="<your_public_key>" />
    <input type="hidden" name="currency" value="USD" />
    <input type="hidden" name="description" value="Some goods" />
    <input type="hidden" name="amount" value="100" />
    <input type="submit" value="Pay" />
</form>

Embedded (iframe or lightbox)¶

The Hosted Payment Page are displayed in an iframe or lightbox within your website. When you redirect your customers to our payment page, the web address for your website remains unchanged, providing a more seamless shopping experience. An iframe or lightbox integration requires a more advanced integration.

We apply responsive web design to payment content displayed in an iframe or lightbox. When the width of the parent page is resized, the content in the iframe or lightbox is automatically adjusted.

Depending on the content being displayed, the height of the iframe or lightbox may increase. For an iframe, the content in the parent page that is below the iframe is pushed down as the payment page content expands vertically.

Set target field to iframe and create HTML tag to insert HPP into. Define selector_id key in widget configuration options. selector_id by default is payment_widget.

<script async src="https://unpkg.com/@paycore/[email protected]/dist/paymentWidget.umd.min.js"></script>
<script>
window.HPPConfig = {
    public_key: "<your_public_key>",
    amount: 100.00,
    currency: "USD",
    description: "Some goods",
    target: "iframe"
};
</script>
<div id="payment_widget" style="width: 375px; height: 600px;"></div>

<form action="https://com.paycore.io/hpp/" method="get" target="payment_frame">
    <input type="hidden" name="public_key" value="<your_public_key>" />
    <input type="hidden" name="currency" value="USD" />
    <input type="hidden" name="description" value="Some goods" />
    <input type="hidden" name="amount" value="100" />
    <input type="submit" value="Pay" />
</form>
<iframe name="payment_frame" src="" id="payment_frame" width="100%" height="600"></iframe>

Payment Widget¶

Library¶

The fastest and easiest way to use our HPP is to use paymentWidget.js.

To integrate the widget into your website, you can download it from the CDN or integrate the library into your javascript build.

Repository: unpkg.com/@paycore/payment-widget-js

CDN:

<script async src="https://unpkg.com/@paycore/[email protected]/dist/paymentWidget.umd.min.js"></script>

<script async src="https://unpkg.com/@paycore/[email protected]/dist/paymentWidget.umd.js"></script>

Initialization¶

We offer three ways to integrate payment_widget.js into your website, so you can pick the one that best fits your requirements:

1. window.payment_widget.init()

   payment_widget.js can only be run synchronously with this method.

2. window.HPPConfig

   Our recommended option, which allows you to run payment_widget.js synchronously or asynchronously.

After you have specified all the required fields and customized your HPP, you will see a list of payment methods.

<script src="https://unpkg.com/@paycore/[email protected]/dist/paymentWidget.umd.min.js"></script>
<script>
window.payment_widget.init({
    public_key: "<your_public_key>",
    amount: 100.00,
    currency: "USD",
    description: "Some goods",
    target: "redirect"
    });
</script>

<script async src="https://unpkg.com/@paycore/[email protected]/dist/paymentWidget.umd.min.js"></script>
<script>
window.HPPConfig = {
    public_key: "<your_public_key>",
    amount: 100.00,
    currency: "USD",
    description: "Some goods",
    target: "redirect"
    };
</script>

Configuration¶

<script src="https://unpkg.com/@paycore/[email protected]/dist/paymentWidget.umd.min.js"></script>
<script>
window.payment_widget.init({
    base_url: "https://pay.yourdomain.сom/hpp/",
    selector_id: "payWidget",
    frame_id: "payFrame",
    target: "redirect",
    public_key: "<your_public_key>",
    amount: 100.00,
    currency: "USD",
    description: "Some goods"
    });
</script>

<script async src="https://unpkg.com/@paycore/[email protected]/dist/paymentWidget.umd.min.js"></script>
<script>
window.HPPConfig = {
    base_url: "https://pay.yourdomain.сom/hpp/",
    selector_id: "payWidget",
    frame_id: "payFrame",
    target: "redirect",
    public_key: "<your_public_key>",
    amount: 100.00,
    currency: "USD",
    description: "Some goods",
};
</script>

Actions¶

window.payment_widget.init({
    public_key: "<your_public_key>",
    amount: "100.00",
    currency: "USD",
    });

window.payment_widget.reinit({
    public_key: "<your_public_key>",
    amount: "100.00",
    currency: "USD",
    });

window.payment_widget.close({
    frame_id: "<id_of_frame>", // By default: `payment_widget`
    });

Events¶

The widget handles a number of events that are generated by HPP which you can handle for various purposes.

The table below provides the full list of events that you can attach one or more handlers to.

Adding an event handler¶

There are three ways to add an event handler:

• Method 1: The standard approach

  Bind by constant

  window.payment_widget.bindEventListener(payment_widget.events.<EVENT_CONSTANT>, handler)
  

  Bind by name

  window.payment_widget.bindEventListener(<event_name>, handler)
  

  Console logging example

  window.payment_widget.bindEventListener('delete', () => {console.log("Iframe closing handle")})
  

• Method 2: Configuration options

  init()

  window.payment_widget.init({
      public_key: 'pk_test_<your_key>',
      handlers: {
          <event_name>: handler
      }
  });
  

  HPPConfig

  window.HPPConfig = {
      public_key: 'pk_test_<your_key>',
      handlers: {
          <event_name>: handler
      }
  };
  

• Method 3: Listen iframe events

  You could listen to events directly from iframe if you don't use our Payment Widget (JS).

  window.addEventListener(<event_name>, callback, false);
  

  Get more about Cross-window communication documentation.

Can we help?¶

Thanks for using Corefy. If you need any help or support, then message our support team at support@corefy.com.