Skip to content

Checkout: API Reference

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

Redirecting customers to Checkout

You can use a Payment Link (standard HTML form) or Payment Widget (JS) to collect and pass payment and customer details to Checkout. 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 api.paymega.io/hpp/.

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

You could use a secure method of obtaining a pre-created Payment Invoice ID before redirecting customers to Checkout, as described in Secure redirection method.

Tips for improving customer experience

  • Any parameters that you pass through in your HTML form, such customer details as first name, last name, and email, is autocompleted (or completed and hidden) as appropriate, on the Checkout making it easier for the customer to fill these forms
  • You can customise the appearance of the Checkout
  • To maximise conversion, Paymega recommends you redirect customers to the Checkout in the same browser window or embed the Checkout in an iFrame (see Embedding on Quickstart Guide)

Secure redirection method

Use this method to ensure that details of the payment are communicated securely between your server and Paymega.

Important!

We strongly recommend you use this method when redirecting your customers to Paymega, as it does not require sending any payment parameters to their browser. Also, this method prevents customers from being able to view or modify any hidden parameters in your source code.

The redirection process is as follows:

  1. Your web server makes a standard POST request with the payment parameters, using the Private API
  2. The Paymega 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 that contains a Payment Invoice ID value
  4. With this Payment Invoice ID value, you can redirect the customer to:
api.paymega.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

The selected integration type determines how you set the Checkout parameters.

General requirements

Checkout works only with:

  • active commerce account
  • which allows public creation for payment invoices
  • and has at least one active currency account

Please contact your account Administrator if you need to set up those options for it.

Language Encoding for Text Parameters

All text fields use UTF-8 encoding.

URL parameters

All URL parameters must include the scheme at the front of the URL (like https://). For example, instead of www.google.co.uk, you would need to use https://www.google.co.uk.

Basic

All following fields are required*:

Key Type Description
public_key* string Public key of your account (find it in the Dashboard ).
amount* float The payment invoice amount.
currency* (string) CurrencyCode The payment invoice currency (three-letter ISO 4217 code).
Example: Basic payment
<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="api.paymega.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>

Available currencies

You can only create payments in currencies that have been enabled for your account. Please contact your Paymega account manager if you need to process in additional currencies.

Test mode

When you're processing live payments, replace Public Live Key with Public Test Key.

Optional

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

Key Type Description
reference_id string Unique reference id of payment invoice.
description string Description of the payment invoice.
expires int UNIX timestamp, UTC+0
Example: Payment with optional details
<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="api.paymega.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>

Idempotency

Idempotency prevents the processing of duplicate payment requests by using unique keys set in reference_id property.

Each reference_id should be a Unique Identifier, and you should manage the generation of your keys to ensure that duplicates are not generated accidentally. Duplicate keys are only detected when provided by the same account, so only submissions you provide can throw a duplicate error.

UUIDs are very large (128-bit) numbers. To avoid the "accidental" creation of duplicate keys, we recommend using a randomly generated UUID for your reference_id. It is especially important when generating reference_id for different payment requests.

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:

Key Type Description
reference_id* string The customer's unique reference ID.
email string The customer's email address.
phone string The customer's phone number.
name string The customer's name.
metadata array[key:value] The customer's metadata.
Example: Payment with customer details
<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="api.paymega.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

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

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

Key Type Description
service (string) ServiceCode The code of service you want to autoprocess. Example: bitcoin_btc_hpp.
service_fields (object) string[key:value] Fields of selected service. Example: [{'name': 'John Doe'}]
Example: Payment with auto process
<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="api.paymega.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>
Try it out in Sandbox

You can check all enable services in the Sandbox and configure payment link or code snippet to execute on the client page.

Sandbox

Return URL

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

If you don't provide return_url, customers are redirected to one of Paymega's default result pages where the payment journey ends.

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

Key Type Description
return_url string The customer's redirect URL at the end of the payment process.

Paymega configures the return URL for you in your account, but you can also send return_url values and override this option.

FFor 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.

Example: Payment with custom return URL
<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="api.paymega.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>

Warning

Unlike the return URL, it's not possible to override the Callback URL cause of the security violations. You must specify it in the Account settings .

Localisation

Now Checkout supports three main languages: English, Ukrainian, Russian. By default, it uses the client’s browser language, but you can specify the language for page display.

Key Type Description
locale string The ISO 639-1 code of one of predefined languages. Enum: en, uk, ru (Default: The user browser language).
Example: Payment with predefined language for the UI
<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="api.paymega.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 favourite things about Checkout is its customizability. By following this styling guide, you can make changes to just about anything.

Display

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

Key Type Description
hide_header bool Flag to hide header on Checkout. Default: false.
hide_footer bool Flag to hide footer on Checkout. Default: false.
hide_progress_bar bool Flag to hide progress bar on Checkout. Default: false.
hide_method_filter bool Flag to hide method filter bar on Checkout. Default: false.
hide_lifetime_counter bool Flag to hide lifetime counter on Checkout (if the expires date was passed). Default: false.

Filtering

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

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

Key Type Description
show_methods array[method_codes] Flag to display specific payment methods.
hide_methods array[method_codes] Flag to prevent specific payment methods from being displayed.

Configured payment services

All the configured payment services for your account are available in the Dashboard Account SettingsPayment Methods.

Styling

Checkout can be customized to fit seamlessly with your brand. You can use different selectors, properties and values.

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

The available options for the styling object:

Key Description
pay_button_label Label on pay button translated on all supported languages. Enum: pay, subscribe, donate.
show_method_logo Payment methods have icons or logos to show on their card previews.
theme Our themes include several options to change the layout, colours and fonts of your payment page. Enum: light, dark.
success_color Success colour to show success notifies/messages.
warning_color Warning colour to show warning notifies/messages.
danger_color Danger colour to show danger notifies/messages.
info_color Info colour to show information notifies/messages.
primary_color Accent colour.
primary_variant Based on the primary colour or can be passed by you. If the primary colour is dark, then this variable will be lighter. Used on most important UI components (stepper, buttons).
primary_text_color Primary text colour that used mostly everywhere.
primary_background_color Primary background colour.
on_primary_color The most convenient colour on elements with primary colour fill. Based on primary_background_color colour or can be passed by you.
secondary_color Secondary colour.
secondary_variant Based on the secondary colour or can be passed by you. If the secondary colour is dark, this variable will be a few tones lighter. Used on secondary UI components.
secondary_text_color Secondary text colour used mostly on secondary UI components.
secondary_background_color Secondary background colour (payment method cards).
on_secondary_color The most convenient color on elements with secondary_background_color fill. Based on secondary_background_color colour or can be passed manually by you.
Example: Change the pay button label
payment_widget.init({
public_key: "YOUR_COMMERCE_ACCOUNT_PUBLIC_KEY",
amount: "100.00",
currency: "USD",
style: {
    pay_button_label: "pay",
    },
})

Metadata

Configuration property:

Key Description
metadata Set of key/value pairs. Additional key:value info about your invoice.

In the example above we suppose you store the reference_id that is unique to the payment in your order table. This way, your back-end can look-up the order for this payment when Paymega sends the callbacks. Your back-end 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 can ask Paymega to remember the unique identifier of your order by instructing the Paymega 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. Paymega stores the metadata for you and include the metadata in the response when you fetch the payment while processing the callbacks. It is another way to connect orders and payments. We advise using the metadata approach. It is the most popular approach and the easiest to implement.

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

For example, if you're a data service provider and want to store certain features of a particular plan, such as "Usage Limit" or "Speed within limit", 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, JSON will look like:

Example: Payment with additional fields (metadata)
<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="api.paymega.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>

Warning

  • Metadata is completely for your reference and not visible to customers
  • Metadata is not a filter criterion or a part of the exports

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 Checkout is displayed full-page in a browser. When your customers are redirected to check out, the web address for the Checkout page is displayed. Full-page redirect supports over 60 payment methods.

Set the target field to redirect for Payment Widget integration method.

Example
<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="api.paymega.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 Checkout is 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 displayed content, the height of the iFrame or lightbox may increase. For an iFrame, the content in the parent page below the iFrame is pushed down as the payment page content expands vertically.

Set the target field to iFrame and create an HTML tag to insert Checkout. Define selector_id key in widget configuration options. selector_id value by default is payment_widget.

Example
<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="api.paymega.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>

Security and cross-domain browser restrictions

It's although possible that using iFrames can introduce known usability, security and cross-domain browser issues.

Keep the following in mind:

  • Some redirect payment methods, such as iDEAL, do not allow displaying their pages in an iFrame; they break out of it. Other redirect payment methods may require more available screen space than your iFrame allows. You should also be prepared to handle the difference in behaviour for the payment callback URL, as once the payment completes you may not be in an iFrame anymore.
  • Another problem you may face is the browser's cookie policy. The Checkout solution requires cookies. Using an iFrame means that the browser may impose restrictions regarding the conditions in which cookies are allowed to be set within the iFrame. While there are workarounds to get the browser to accept cookies in a default configuration, the shopper may have configured a more restrictive policy. The most common problem is with Apple Safari and Google Chrome browsers: by default, they require user-initiated page loading inside an iFrame. Firstly, it means that the iFrame needs to be loaded with a page hosted at the parent domain. Secondly, on this page, the user needs to actively click on a button submitting the redirect to the Checkout.

Paymega cannot guarantee that all payment methods will work when using an iFrame, nor that the behaviour of a payment method will remain the same. Furthermore, transaction processing with the redirect method in the test and live environments may differ.

Payment Widget

Library

The fastest and easiest way to use our Checkout 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 specifying all the required fields and customizing your Checkout, you can 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

Key Type Description
base_url string The link with your Checkout location. It is necessary in case of placing Checkout on your domain (for example: pay.yourdomain.сom).
selector_id string ID of the DOM element you want to insert Checkout. Default: payment_widget.
frame_id string ID of the inserted frame. Default: payment_frame.
target string you can insert Checkout inside iFrame on the page or open Checkout in a new tab in the browser (iFrame, redirect. Default: iFrame).
Example: Additional widget 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

Method Description
init(object) Accepts configuration and initializes the widget with Checkout.
reinit(object) Accepts configuration and reinitializes the widget.
close(object) Accepts configuration and closes the widget.
Examples
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 several events that are generated by Checkout, and you can manage it for various purposes.

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

Event name When
ready Triggered when Checkout is registered on the global namespace and safe to use.
rendered Triggered when Checkout is rendered in iFrame and ready to use by a customer.
return When a user clicks on the "Return to shop" button on the success page. Removes the iFrame from the client page by default.

Adding an event handler

Events constants

Event constants on the JavaScript API are accessible via payment_widget.events.

There are three ways to add an event handler:

  • Method 1: The standard approach

Examples

window.payment_widget.bindEventListener(payment_widget.events.<EVENT_CONSTANT>, handler)
window.payment_widget.bindEventListener(<event_name>, handler)
window.payment_widget.bindEventListener('delete', () => {console.log(" iFrame closing handle")})
  • Method 2: Configuration options

Examples

window.payment_widget.init({
    public_key: 'pk_test_<your_key>',
    handlers: {
        <event_name>: handler
    }
});
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).

Example

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

Get more at Documentation MDN: Window.postMessage() .

Can we help?

Thanks for using Paymega. If you need any help or support, then message our support team !