Hosted Payment Page

Genome's Hosted Payment Page (HPP) lets you accept payments without handling sensitive payment data on your own servers. You redirect your user to Genome's payment page, Genome processes the payment, and you receive a server-to-server callback with the result.

Overview

The HPP integration works in three steps:

Your server prepares a signed payment request and redirects the user to https://pay.genome.eu.
The user completes the payment on Genome's hosted page.
Genome sends a server-to-server callback to your configured URL with the payment result.

Before you start

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.

Hosted Payment Page session initiation

Step 1 - Derive the signing key

To derive the signing key, compute the SHA-256 hash of your API secret as raw bytes. Your API key and API secret are available in the Genome merchant dashboard under particular Payment page settings. The HMAC signing key is not your raw API secret. You must first compute its SHA-256 digest. Tokens signed with the raw secret will always be rejected.

Genome requires the HMAC key to meet a minimum length requirement regardless of how long your API secret is. Hashing it first guarantees a consistent 32-byte key for all secrets.

Step 2 - Build the JWT

Assemble your claims and sign the token using HMAC-SHA256 with the key derived in Step 1.

// Node.js — full example
const crypto = require('crypto');
const jwt = require('jsonwebtoken');

const apiKey = 'your_api_key';
const apiSecret = 'your_payment_page_secret';

// The signing key is the SHA-256 hash of your Payment Page secret.
const signingKey = crypto
  .createHash('sha256')
  .update(apiSecret)
  .digest();

const now = Math.floor(Date.now() / 1000);

const token = jwt.sign(
  {
    // Required — identity & timing
    iss: apiKey,                  // Your API key
    sub: 'order-12345',           // Your order or user ID
    iat: now,                     // Issued at (Unix timestamp)
    exp: now + 30 * 60,           // Expires in 30 minutes
    jti: crypto.randomUUID(),     // Generate a new unique ID for every token

    // Required — amount
    VALUE_AMOUNT_ISO: 'EUR',
    VALUE_AMOUNT_RAW: '49.99',

    // Recommended — session data
    VALUE_ORDER_ID: 'order-12345',
    VALUE_USER_ID: 'user-abc',
    VALUE_SUCCESS_URL:  'https://yoursite.com/payment/success',
    VALUE_FAILURE_URL:  'https://yoursite.com/payment/failure',
    VALUE_EMAIL: 'user@example.com',
    VALUE_FIRST_NAME: 'Jane',
    VALUE_LAST_NAME: 'Doe',
    VALUE_VERIFIED_USER: true,

    // Options — control payment page display
    OPTION_SHOW_EMAIL: false,
    OPTION_ALLOW_EDIT_PRESET: true,

    // Custom metadata — forwarded in callbacks
    custom_campaign_id: 'summer2026',
  },
  signingKey,
  {
    algorithm: 'HS256',
  }
);

Tokens are also rejected if iat is older than 30 minutes, regardless of exp.

Never build or sign the JWT in the browser - the API secret must never be exposed to your customer.

The JWT Claims References and Payment Page parameters are listed in the tables below.

Step 3 - Redirect the user

Pass the signed token as a jwt URL parameter when redirecting to the HPP:

https://pay.genome.eu?jwt=<your_signed_token>

JWT Claims Reference

Claims (required)

The token is rejected if any of these are missing.

Claim	Type	Description
iss	string	API key - identifies the payment page issuer.
sub	string	Session subject. Use your order ID or user ID.
iat	number	Issued-at time (Unix seconds). Must be within 30 minutes of the current time.
exp	number	Expiry time (Unix seconds). Token is rejected after this time.
jti	string	Unique token ID. Use a UUID. Generate a fresh value for every token.
VALUE_AMOUNT_ISO	string	Currency code in ISO 4217 format, e.g. EUR.
VALUE_AMOUNT_RAW	string	Transaction amount as a decimal string, e.g. 49.99.

Payment Page parameters of request - VALUE_* (optional)

All VALUE_ claims are case-insensitive. Only values marked as configurable on your payment page are accepted - others are silently ignored.

Claim	Type	Description
VALUE_PAYMENT_METHOD	string	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
VALUE_COUNTRY	string	Pre-select a country, e.g. DEU.
VALUE_ORDER_ID	string	Merchant's order (transaction) identifier.
VALUE_USER_ID	string	User identifier on your platform.
VALUE_MCC	string	MCC of the operation, used in payment method routing.
VALUE_SUCCESS_URL	string	URL to redirect to on successful payment.
VALUE_FAILURE_URL	string	URL to redirect to on failed payment.
VALUE_EMAIL	string	Payer's email address.
VALUE_PHONE	string	Payer's phone number.
VALUE_FIRST_NAME	string	Payer's first name.
VALUE_LAST_NAME	string	Payer's last name.
VALUE_ADDRESS	string	Payer's street address.
VALUE_ZIP	string	Payer's ZIP or postal code.
VALUE_CITY	string	Payer's city.
VALUE_DESCRIPTION	string	Description of the operation.
VALUE_CUSTOMER_TYPE	string	Possible values: new, trusted, VIP, which can be used in improving routing and pricing logic.
VALUE_LANG	string	Default - English. It's possible to provide a pre-selected payment page language. Possible values are EN, UA, LT.
VALUE_ROUTING_CODE	string	Value for payment method routing.
VALUE_SESSION_LIFETIME	string	Session lifetime in seconds. If no value is provided, then standard duration (30 min.) will be applied.
VALUE_VERIFIED_USER	boolean	Payer’s KYC status at merchant platform.

Payment Page parameters of request - OPTION_* (optional)

All OPTION_ claims are case-insensitive and control display and behaviour on the payment page.

Claim	Type	Description
OPTION_SHOW_COUNTRY	boolean	Show or hide the country selector.
OPTION_SHOW_EMAIL	boolean	Show or hide the email field.
OPTION_SHOW_PHONE	boolean	Show or hide the phone field.
OPTION_SHOW_FIRST_LAST_NAME	boolean	Show or hide the first and last name fields.
OPTION_SHOW_ADDRESS	boolean	Show or hide the address field.
OPTION_SHOW_ZIP	boolean	Show or hide the ZIP/postal code field.
OPTION_SHOW_CITY	boolean	Show or hide the city field.
OPTION_ALLOW_EDIT_PRESET	boolean	If true all data passed from merchant website to the payment page (for example, email, first and last names) will be editable. Otherwise, the fields will be non-editable or not rendered at all.

Custom parameters of request - custom_* (optional)

Any merchant-defined metadata. Case-sensitive. Forwarded verbatim in payment callbacks.

Claim	Type	Description
custom_<your_key>	any	Your own metadata, e.g. custom_campaign_id, custom_affiliate_ref.

Deprecated - Legacy signature calculation

This integration method is deprecated. New integrations should use the JWT-based HPP session initiation described above.

Existing integrations using MODE_A_TS will continue to work during the transition period. We will provide at least 90 days' advance notice before this method is discontinued, in line with PSD2 requirements. No immediate action is required.

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

Before you start

Hosted Payment Page session initiation

Step 1 - Derive the signing key

Step 2 - Build the JWT

Step 3 - Redirect the user

JWT Claims Reference

Deprecated - Legacy signature calculation

HPP signature calculation

Callback

Pay by Bank

Credit/Debit Card

WEB SDK Integration

On this page