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

Before you can open a merchant account, both your personal wallet and business wallet must be confirmed. You can verify your wallets on the my.genome.eu dashboard.

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

Open a merchant account and submit the required data for verification.
Create a payment page once the merchant account is confirmed:
- Enable the methods you want available at checkout.
- Set the URL where Genome will send payment callbacks and define your success and decline redirect URLs.
- (optional) Choose which customer contact details to collect during the HPP session.
Choose settlement accounts in the merchant account settings.
Make an integration using the following document.
Test your payment page using the payment page in Test mode.
Check that redirect URLs work correctly, and the callback data is received.
Once you have completed your HPP integration and tested end-to-end, return to your payment page settings and activate your payment page. Real transactions will only be processed on activated payment pages.

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	YES	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

A callback is a server-to-server HTTP POST notification that Genome sends to your configured callback URL when a payment session reaches a terminal state or a meaningful intermediate milestone. Your callback URL is set in Payment page settings in the Genome Portal. We recommend using HTTPS for the callback URL.

Always respond with a 200 OK HTTPS response, which tells Genome that the event has been received and does not need to be resent.

The number of callbacks depends on the payment method the end user selects in your HPP.

Pay by Bank

Genome sends up to four callbacks as the payment progresses through its settlement stages:

Event value	When it is sent
INCOMING_PAYMENT_CREATED	Sent when the end user gives consent, the payment is successfully initiated at the bank and end user returns to Genome without errors.
INCOMING_PLEDGE	Sent when Genome receives confirmation from external systems that funds are on their way.
INCOMING_SUCCESS	Sent when funds are received into the merchant's account. This is the definitive final confirmation.
INCOMING_DECLINE	Sent when the hosted payment page session is declined. This means that no successful transaction was initiated during the lifetime of the hosted payment page session.

Credit/Debit Card

Card payments are synchronous. The outcome is known immediately after 3D Secure (if required) and the acquirer's response. Genome sends exactly two callbacks per completed card session:

Event value	When it is sent
INCOMING_SUCCESS	Sent when funds are received into the merchant's account. This is the definitive final confirmation.
INCOMING_DECLINE	Sent when the hosted payment page session is declined. This means that no successful transaction was initiated during the lifetime of the hosted payment page session.

Important – callbacks may arrive out of order

These callbacks may be received in any order. Each callback contains information accurate at the time it was sent. Always treat INCOMING_SUCCESS as the authoritative final confirmation - regardless of the order it arrives in - because it is the only event that confirms funds are in your account.

Description of the callback parameters:

Parameter	Format and rule	Data type	Description
event	mandatory	string enumeration (INCOMING_PAYMENT_CREATED, INCOMING_PLEDGE, INCOMING_SUCCESS, INCOMING_DECLINE, PAYOUT_SUCCESS, PAYOUT_DECLINE)	Type of callback.
merchant_account_id	mandatory	uint64	Genome merchant account ID.
is_test	mandatory	boolean	true if a test payment method was used; false for live payments.
session	conditional	object	HPP session data when present.
id	mandatory	string	The unique session ID.
status	mandatory	string enumeration	Session status at the time this callback was sent.
created_at	mandatory	ISO RFC 3339 time format "yyyy-MM-dd'T'HH:mm:ss'Z'"	Time the HPP session was created.
order	mandatory	object	Order data.
id	mandatory, if provided by merchant	string	Order ID supplied by the merchant during HPP session initialisation, or transaction_unique_id for Host-to-Host.
user_id	mandatory, if provided by merchant	string	User identifier supplied by the merchant.
description	optional	string	Order description.
amount	mandatory	amount object	Amount data.
amount	mandatory	decimal	Transaction amount.
currency	mandatory	string (ISO 4217)	Transaction currency code, e.g., EUR.
payment_method_type	mandatory	string enumeration (CC, OPEN_BANKING)	Type of payment method.
idempotency_id	optional	string	Unique payment ID. Also used as EndToEndID in SEPA transfers.
userdata	optional	object	End-user data.
first_name	optional	string	The customer's first name.
last_name	optional	string	The customer's last name.
email	optional	string	The customer's email address.
phone	optional	string	The customer's phone number.
address	optional	address object	The customer's address.
country	optional	string	The customer's country.
state	optional	string	The customer's state.
city	optional	string	The customer's city.
address	optional	string	The customer's street address.
zip	optional	string	The customer's ZIP or postal code.
shipping_address	optional	address object	The customer's shipping address data.
country	optional	string	The shipping country.
state	optional	string	The shipping state.
city	optional	string	The shipping city.
address	optional	string	The shipping street address.
zip	optional	string	The shipping ZIP or postal code.
error	conditional	error object	Error data. Present when an error occured.
code	mandatory	string	Error code.
message	mandatory	string	Error message.
transaction	conditional	object	Transaction data. Present when a transaction was created for this session.
id	mandatory	uint64	Unique transaction ID.
type	mandatory	string enumeration (SEPA_INSTANT_INCOMING, SEPA_INCOMING, PF_SALE, PF_SALE3D)	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 the transaction was created.
processed_at	optional	ISO RFC 3339 time format "yyyy-MM-dd'T'HH:mm:ss'Z'"	Time when the transaction was processed.
amount	mandatory	amount object	Amount data.
amount	mandatory	decimal	Transaction amount.
currency	mandatory	string ISO A3 currency code	Transaction currency code.
description	mandatory	string	Payment description.
idempotency_id	optional	string	Unique payment ID. Also used as EndToEndID in SEPA transfers.
bank_transfer	conditional	object	Open Banking only. Present when payment_method_type is OPEN_BANKING. Not present for card payments.
sender_iban	mandatory	string	Sender’s IBAN.
sender_bic	mandatory	string	Sender bank’s BIC.
sender_name	mandatory	string	Sender’s name.
credit_card	conditional	object	Card payment only. Present when payment_method_type is CC. Not present for Open Banking 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. Present when an error occured.
code	mandatory	string	Error code.
message	mandatory	string	Error message.
custom	optional	object	Key-value pairs originally sent by the merchant during HPP session initialisation or a Host-to-Host request. Echoed back as-is.

The transaction object contains either a bank_transfer sub-object or a credit_card sub-object - never both at the same time. Which one appears depends on the payment method:

OPEN_BANKING payments: bank_transfer is populated; credit_card is absent.
CC payments: credit_card is populated; bank_transfer is absent.

Use the top-level order.payment_method_type field (OPEN_BANKING or CC) to determine which sub-object to expect.

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

Pay by Bank

Credit/Debit Card

WEB SDK Integration

On this page