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 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 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, Corefy 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 Corefy.

Important!

We strongly recommend you use this method when redirecting your customers to Corefy, 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 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 that contains a Payment Invoice ID value
  4. With this Payment Invoice ID value, you can redirect the customer to:
https://com.paycore.io/hpp/?cpi=<PAYMENT_INVOICE_ID>
<script src="https://unpkg.com/@paycore/[email protected]/dist/merchantWidget.umd.js"></script>
<script>
window.widget.init({
    cpi: "<PAYMENT_INVOICE_ID>",
});
</script>
<div id="merchant-widget-mount-point" 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 src="https://unpkg.com/@paycore/[email protected]/dist/merchantWidget.umd.js"></script>
<div id="merchant-widget-mount-point" style="width: 375px; height: 600px;"></div>
<script>
window.widget.init({
    public_key: "your_public_key", // replace the value with YOUR commerce public key
    baseUrl: "https://com.paycore.io/hpp/",
    flow: "iframe",
    selector: "merchant-widget-mount-point",
    amount: 100.00,
    currency: "USD"
});
</script>
<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>

Available currencies

You can only create payments in currencies that have been enabled for your account. Please contact your Corefy 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/merchantWidget.umd.js"></script>
<script>
window.widget.init({
    public_key: "<your_public_key>",
    amount: 100.00,
    currency: "USD",
    reference_id: "<your_unique_reference_id>",
    description: "Some goods",
    expires: 1602414000
});
</script>
<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>

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/merchantWidget.umd.js"></script>
<div id="merchant-widget-mount-point" style="width: 375px; height: 600px;"></div>
<script>
window.widget.init({
    baseUrl: "https://com.paycore.io/hpp/",
    flow: "iframe",
    selector: "merchant-widget-mount-point",
    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>
<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>

Autoprocessing

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 autoprocessing
<script async src="https://unpkg.com/@paycore/[email protected]/dist/merchantWidget.umd.js"></script>
<div id="merchant-widget-mount-point" style="width: 375px; height: 600px;"></div>
<script>
window.widget.init({
    baseUrl: "https://com.paycore.io/hpp/",
    flow: "iframe",
    selector: "merchant-widget-mount-point",
    public_key: "<your_public_key>",
    amount: 100.00,
    currency: "USD",
    service: "paypal_usd_hpp"
});
</script>
<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>
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 Corefy'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.

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

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.

Example: Payment with custom return URL
<script src="https://unpkg.com/@paycore/[email protected]/dist/merchantWidget.umd.js"></script>
<div id="merchant-widget-mount-point" style="width: 375px; height: 600px;"></div>
<script>
    window.widget.init({
        public_key: "your_public_key", // replace the value with YOUR commerce public key
        baseUrl: "https://com.paycore.io/hpp/",
        flow: "iframe",
        selector: "merchant-widget-mount-point",
        return_url: "https://somedomain.com/",
        amount: 100.00,
        currency: "USD",
        description: "Some goods"
});
</script>
<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>

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 src="https://unpkg.com/@paycore/[email protected]/dist/merchantWidget.umd.js"></script>
<div id="merchant-widget-mount-point" style="width: 375px; height: 600px;"></div>
<script>
    window.widget.init({
        public_key: "your_public_key", // replace the value with YOUR commerce public key
        baseUrl: "https://com.paycore.io/hpp/",
        flow: "iframe",
        selector: "merchant-widget-mount-point",
        locale: "uk",
        amount: 100.00,
        currency: "USD",
        description: "Some goods"
    });
</script>
<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 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
window.widget.init({
    public_key: "your_public_key", // replace the value with YOUR commerce public key
    baseUrl: "https://com.paycore.io/hpp/",
    flow: "iframe",
    amount: "100.00",
    currency: "USD",
    style: {
        pay_button_label: "Pay now",
        },
    });

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 Corefy 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 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 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 Corefy'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 src="https://unpkg.com/@paycore/[email protected]/dist/merchantWidget.umd.js"></script>
<div id="merchant-widget-mount-point" style="width: 375px; height: 600px;"></div>
<script>
window.widget.init({
    public_key: "your_public_key", // replace the value with YOUR commerce public key
    baseUrl: "https://com.paycore.io/hpp/",
    flow: "iframe",
    selector: "merchant-widget-mount-point",
    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>
<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>

Note

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

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 iframes; 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.

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

Can we help?

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