Hosted Payment Page

Overview

Now you can easily receive payments and increase your revenue in a few clicks. This guide will cover some of the basics of setting up your account, receiving payments, and using your account.

HPP integration flow

To get started with receiving the payments using Genome hosted payment pages, you need to:

Sign up at genome.eu;
Start a business wallet;
Start a merchant account;
Create a payment page;
Create payment method(s);
Make an integration using the following document;
Test your payment page using test payment methods;
Check that redirect URLs work correctly and callback data is received;
Switch off the test payment method(s) and run in production.

Payment Page

Parameters of request

Parameter name	Validation	Required	Description
api_key	String	YES	Your personal API key from genome portal.
signature	String	YES	Digital signature. The generation is explained below.
amount	String	YES	Amount of the transaction.
currency_iso	String	YES	ISO 4217 code of the transaction currency. Use "XTS" test currency for test mode.
allow_edit_preset	Boolean	OPTIONAL	If true all data passed from merchant website to Genome Hosted Payment Page (for example, email, first&last names) will be editable. Otherwise, the fields will be non-editable or not rendered at all.
show_first_last_name	Boolean	OPTIONAL	Option to display 'first_name' and 'last_name' fields.
show_address	Boolean	OPTIONAL	Option to display 'address' field or not.
show_city	Boolean	OPTIONAL	Option to display 'city' field or not.
show_country	Boolean	OPTIONAL	Option to display 'country' field or not.
show_email	Boolean	OPTIONAL	Option to display 'email' field or not.
show_phone	Boolean	OPTIONAL	Option to display 'phone' field or not.
show_zip	Boolean	OPTIONAL	Option to display 'zip/postal code' field or not.
ts_nonce	String	OPTIONAL	Timestamp for signature calculation.
order_id	String	OPTIONAL	Merchant's order (transaction) identifier.
mcc	String	OPTIONAL	MCC of operation, used in payment method routing.
description	String	OPTIONAL	Description of operation.
first_name	String	OPTIONAL	Payer's first name.
last_name	String	OPTIONAL	Payer's last name.
phone	String	OPTIONAL	Payer's phone number.
email	String	OPTIONAL	Payer's email.
user_id	String	OPTIONAL	User identifier on merchant's site.
country	ISO3 String	OPTIONAL	Payer's country ISO 3166-1 alpha-3 code.
city	String	OPTIONAL	Payer's city.
address	String	OPTIONAL	Payer's address.
zip	String	OPTIONAL	Payer's zip.
payment_method	String	OPTIONAL	A parameter that will overwrite the payment methods configured on the Payment Page if provided. Possible values are: 1 - card, 2-9 reserved for card types 10 - Bank Transfer
customer_type	String	OPTIONAL	Possible values: new, trusted, VIP, which can be used in improving routing and pricing logic.
lang	String	OPTIONAL	Default - English. It's possible to provide a pre-selected payment page language. Possible values are “EN, UA, LT“
success_url	String	OPTIONAL	Redirect URL value in case of a successful transaction.
failure_url	String	OPTIONAL	Redirect URL value in case of an unsuccessful transaction.
routing_code	String	OPTIONAL	Value for payment method routing.
session_lifetime	String	OPTIONAL	Session lifetime in seconds. If no value is provided, then standard duration (30m) will be applied.
custom_<any_value>	String	OPTIONAL	Any custom parameters should start with 'custom_' prefix.

Code example:

<form action="https://pay.genome.eu/" target="_blank">
    <input type="hidden" name="api_key" value="nBE7sEDJA0xz0xo0aH99JmCgXH6flFASWXjPwgsYBC7rKaLwNwcTe3dvMRW6VtRl" />
    <input type="hidden" name="signature" value="1ad88f89b0bc9ae64da2f3fda68bbe076d3a2c5b82e56cb087c064deb4ef67b5" />
    <input type="hidden" name="amount" value="5" />
    <input type="hidden" name="currency_iso" value="xts" />
    <input type="hidden" name="allow_edit_preset" value="true" />
    <input type="hidden" name="show_first_last_name" value="true" />
    <input type="hidden" name="show_address" value="true" />
    <input type="hidden" name="show_city" value="true" />
    <input type="hidden" name="show_country" value="true" />
    <input type="hidden" name="show_email" value="true" />
    <input type="hidden" name="show_phone" value="true" />
    <input type="hidden" name="show_zip" value="true" />
    <input type="hidden" name="ts_nonce" value="1645000903012" />
    <input type="hidden" name="order_id" value="124334" />
    <input type="hidden" name="mcc" value="666" />
    <input type="hidden" name="description" value="test description" />
    <input type="hidden" name="first_name" value="John" />
    <input type="hidden" name="last_name" value="Doe" />
    <input type="hidden" name="phone" value="+37052141409" />
    <input type="hidden" name="email" value="john.doe@gmail.com" />
    <input type="hidden" name="user_id" value="u-id-12345" />
    <input type="hidden" name="country" value="USA" />
    <input type="hidden" name="city" value="New York" />
    <input type="hidden" name="address" value="350 5th Avenue" />
    <input type="hidden" name="zip" value="10118" />
    <input type="hidden" name="payment_method" value="1" />
    <input type="hidden" name="customer_type" value="new" />
    <input type="hidden" name="lang" value="EN" />
    <input type="hidden" name="success_url" value="https://merchant-site.com/success" />
    <input type="hidden" name="failure_url" value="https://merchant-site.com/failure" />
    <input type="hidden" name="routing_code" value="103" />
    <input type="hidden" name="session_lifetime" value="1642596566170" />
    <input type="hidden" name="custom_product" value='id-01' />
    <input type="hidden" name="custom_user_id" value="custom-user-id" />
    <button type="submit">
        Pay
    </button>
</form>

Url of the request: https://pay.genome.eu

HPP signature calculation

The algorithm of signature calculation is explained below.

The SHA256 hash function should be applied to the string with the following format:

Parameter name	Required	Description
api_secret	YES	Your personal secret key, which you created within the Genome portal.
signature_mode	YES	Signature mode, right now 'MODE_A_TS' is only available for merchants. Amount with the timestamp.
timestamp	YES	Unix timestamp in seconds
amount	YES	Amount of the transaction.
currency_iso	YES	Currency of the transaction in ISO 4217 format.
order_id	OPTIONAL	Merchant's order id.
user_id	OPTIONAL	Merchant's user id.
mcc	OPTIONAL	MCC code.

Code example:

STRING: myAwesomeSecret|MODE_A_TS|1647606194|1.00|EUR|order_100500|USER12345|666
SHA256: b743b9408dea1ec1c5385f79981cad6a4db4dc8e8318abf97c8508df9b4bd9bd

STRING: myAwesomeSecret|MODE_A_TS|1647607015|5.00|USD|||
SHA256: b548478c7afec5e600d3fdc1cc5de5b0ef0c3e322a00aed657e440d5a0d45e4b

STRING: myAwesomeSecret|MODE_A_TS|1647607116|100.52|EUR||USER12345|666
SHA256: 99341a76a53311c43c7a28bf422027122d6b85cc05b0d693b4a52d6152c20cfa

STRING: myAwesomeSecret|MODE_A_TS|1647607116|1234.56|USD|||616
SHA256: aa87dfdd63b6902b451e26d1a74f360bdc1655cb90bc5945d21c04a479cac5b3

String should be formated using | separator in this way:

api_secret

signature_mode

timestamp

amount

currency_iso

order_id

mcc

Callback

Callback purpose: callback is a final response by Genome regarding a transaction status. It is recommended to use HTTPS protocol for the callback URL.

Description of the callback parameters:

Parameter	Format and rule	Data type	Description
event	mandatory	string enumeration (INCOMING_PLEDGE, INCOMING_SUCCESS, PAYOUT_SUCCESS, PAYOUT_DECLINE)	Type of callback.
merchant_account_id	mandatory everywhere except payouts	uint64	Merchant account ID inside Genome.
is_test	mandatory	boolean	Indicates if a test payment method is used.
session	conditional	object	HPP session data. Filled only if the HPP session is present.
id	mandatory	string	The unique session ID.
status	mandatory	string enumeration	Session status.
created_at	mandatory	ISO RFC 3339 time format "yyyy-MM-dd'T'HH:mm:ss'Z'"	Time when the HPP session was created.
order	mandatory	object	Order data.
id	mandatory, if provided by merchant	string	Order_id in HPP integration; transaction_unique_id in Host-2-Host integration.
user_id	mandatory, if provided by merchant	string	User ID.
description	optional	string	Description.
amount	mandatory	amount object	Amount data.
amount	mandatory	decimal	Transaction amount.
currency	mandatory	string ISO 4217 currency code	Transaction currency.
payment_method_type	mandatory	string enumeration (CC, OPEN_BANKING)	Type of payment method.
idempotency_id	optional	string	Unique payment ID. EndToEndID in the SEPA type bank transfer.
userdata	optional	object	Customer's data.
first_name	optional	string	The first name of the customer.
last_name	optional	string	The last name of the customer.
email	optional	string	Customer’s email.
phone	optional	string	Customer’s phone.
address	optional	address object	Customer's address.
country	optional	string	Customer's country.
state	optional	string	Customer's state.
city	optional	string	Customer's city.
address	optional	string	Customer's address line.
zip	optional	string	Customer's zip.
shipping_address	optional	address object	Shipping address.
country	optional	string	Shipping address.
state	optional	string	Shipping state.
city	optional	string	Shipping city.
address	optional	string	Shipping address line.
zip	optional	string	Shipping zip.
error	conditional	error object	Error data. Filled only if an error is present.
code	mandatory	string	Error code.
message	mandatory	string	Error message.
transaction	conditional	object	Transaction data. Filled only if a transaction is present.
id	mandatory	uint64	The unique transaction ID.
type	mandatory	string enumeration	Transaction type.
status	mandatory	string enumeration	Transaction status.
created_at	mandatory	ISO RFC 3339 time format "yyyy-MM-dd'T'HH:mm:ss'Z'"	Time when transaction was created.
processed_at	optional	ISO RFC 3339 time format "yyyy-MM-dd'T'HH:mm:ss'Z'"	Time when transaction was processed.
amount	mandatory	amount object	Amount data.
amount	mandatory	decimal	Transaction amount.
currency	mandatory	string ISO 4217 currency code	Transaction currency.
description	mandatory	string	Payment description.
idempotency_id	optional	string	Unique payment ID. EndToEndID in SEPA type bank transfer.
bank_transfer	conditional	object	Present for Bank Transfer payments.
sender_iban	mandatory	string	Sender’s IBAN number.
sender_bic	mandatory	string	Sender bank’s BIC.
sender_name	mandatory	string	Sender’s name.
credit_card	conditional	object	Present for CC payments.
card_holder	mandatory	string	Cardholder name.
card_token	optional	string	Card token.
bill_token	optional	string	Bill token.
error	conditional	error object	Error data. Filled only if an error is present.
code	mandatory	string	Error code.
message	mandatory	string	Error message.
custom	optional	object	Key-value pairs, originally sent by the merchant during the HPP session initialization (redirect) or a Host-2-Host request.

Code example JSON:

{
    "event" : "INCOMING_SUCCESS",
    "merchant_account_id" : 123456,
    "is_test" : false,
    "session" : {
        "id" : "one-two",
        "status" : "TODO",
        "created_at" : "2025-12-30T11:22:33Z"
    },
    "order" : {
        "id" : "ordero-numero-uno",
        "user_id" : "this-is-user-id",
        "description" : "This is for testing purposes",
        "amount" : {
            "amount" : 75.88,
            "currency" : "EUR"
        },
        "payment_method_type" : "OPEN_BANKING",
        "idempotency_id" : "aslkdS8ahsdad",
        "userdata" : {
            "first_name" : "Jon",
            "last_name" : "Axelrod",
            "email" : "jon.axelrod@example.com",
            "phone" : "+123456789",
            "address" : {
                "country" : "Ukraine",
                "city" : "Kyiv",
                "address" : "Dripro 1",
                "zip" : "11111"
            },
            "shipping_address" : {
                "country" : "Ukraine",
                "city" : "Kyiv",
                "address" : "Dripro 2",
                "zip" : "22222"
            }
        },
        "error" : {
            "code" : "43",
            "message" : "No error description"
        }
    },
    "transaction" : {
        "id" : 9988,
        "type" : "SEPA_INSTANT_INCOMING",
        "status" : "SUCCESS",
        "created_at" : "2025-12-30T11:30:55Z",
        "processed_at" : "2025-12-30T11:30:58Z",
        "amount" : {
            "amount" : 75.88,
            "currency" : "EUR"
        },
        "description" : "Something",
        "idempotency_id" : "aslkdS8ahsdad",
        "bank_transfer" : {
            "sender_iban" : "UAxxxxxx",
            "sender_bic" : "UAxx",
            "sender_name" : "Jon Axelrod"
        },
        "credit_card" : {
            "card_holder" : "Jon Axelrod",
            "card_token" : "xxx",
            "bill_token" : "yyy"
        },
        "error" : {
            "code" : "43",
            "message" : "No error description"
        }
    },
    "custom" : {
        "custom_uno" : "uno",
        "custom_dos" : 333332
    }
}

Callback headers

Parameter	Type	Description
Content-Type	application/json
X-Request-ID	string	Unique identifier of request. (On any issue provide this identifier to support.)
X-Signature	hexadecimal string	HMACSHA256 of request body
X-Signature-Algorithm	constant	HmacSHA256
X-API-Key	string	Your personal API Key from Genome portal HPP settings.

Hosted Payment Page

Hosted Payment Page

Overview

HPP integration flow

Payment Page

HPP signature calculation

Callback

Host to host API

On this page