Introduction

Welcome to the Genome documentation!

Below you can find the information and tutorials that will teach you how to use Genome host to host integration.

To get started with Genome you’ll need to sign up at my.genome.eu.

Host to host API

Overview

Genome gateway workflow is based on the type of Transaction made. Gateway supports 8 types of transaction requests:

Other definitions:

ECI VALUES

MasterCard ECI value VISA ECI value Description
2 5 Card holder was successfully authenticated
1 6 Authentication could not be completed but a proof of authentication attempt was provided – card is not enrolled*
7 7 Card Holder authentication failed/ Authentication could not be completed due to technical or other problems

*There are two possibilities for this stage: the Issuer bank offered the Customer to enroll online and the Customer declined, or the bank did not make the offer.

Access to Genome Gateway API

Genome live and test host to host API could be reached by the following URLs:

Web Service URL
Live Genome Gateway API Service https://api.genome.eu/api/pf/host-to-host
Gateway API Reference Help https://gateway.genome.eu/help/cc

Genome Gateway supports various transaction flow scenarios, but this document will focus only on the general recommended scenario, described below.

  1. After selecting goods and services, the cardholder presses ‘Buy’ or an equivalent button and proceeds to a page where he can enter or modify delivery information and the payment method. Payment method information may offer various payment methods, like ‘Pay by credit card’ or a similar option. This option should not include card number, expiry date, CVV2/CVC2 or any other card related sensitive information. Because of security risks involved, merchant system should avoid requesting and storing credit card information on the merchant server.

  2. If cardholder selects ‘Pay by credit card’ option, a merchant system must prepare authorization request fields and redirect the cardholder to an ‘Enter credit card information' page on Genome Gateway URL. Alternatively, the merchant system itself may present this page directly to cardholder. This form shall contain all card entry fields and visible/hidden fields relating to the order and merchant as required by the authorization request format.

  3. After receiving the filled-in form by using AUTH/AUTH3D request, Genome Gateway validates request information. If the request fails the validation, Gateway sends an error response back to merchant system.

  4. If the provided card number belongs to a card range with a defined cardholder authentication method (AUTH3D), Gateway calls the corresponding authentication module (3D Secure) which performs protocol-specific processing. If cardholder authentication is unsuccessful, Genome Gateway returns an error message to the merchant system.

  5. Genome Gateway sends an authorization request to the Issuer bank. Upon authorization reception, Gateway prepares and sends a transaction response back to the merchant system. The transaction response contains no credit card information or contains the card number in blinded form only. Gateway sends response messages to the merchant system.

  6. If authorization is successful, the response message will contain the Reference number field, to be used by the merchant system so it can complete or reverse the obtained authorization without the credit card information.

  7. After receiving the online transaction response, the merchant system starts delivery of ordered goods and/or services to the cardholder. At this point, the requested amount is blocked on the cardholder account.

  8. If a merchant would like to make authentication and sale process using one transaction at once, it can choose SALE/SALE3D request which includes AUTH/AUTH3D and SALE transactions consistently.

  9. When the merchant has delivered the goods and services to cardholder, the merchant system sends a SETTLE request (depends on the chosen transaction flow) to complete transaction directly to the Genome Gateway using a reference number to refer to the authorization transaction with its corresponding credit card information. The transaction request should include a message authentication code field for verifying the message's identity.

  10. Genome Gateway validates the incoming message and requests financial completion of the transaction from the bank. At this point, the transaction amount is debited from the cardholder account and the merchant account is credited with the appropriate amount. Gateway sends a response back to merchant system within the response document.

  11. If the merchant is unable to fulfill the cardholder order or if the cardholder cancels the order at a stage allowed by the merchant, the merchant system must send a VOID request to cancel the pending transaction or REFUND request for completed transaction. The merchant system sends this message directly to the Genome Gateway API.

  12. Gateway validates the incoming message and cancels the pending transaction on the Genome Gateway side or requesting to refund for completed transaction from the bank. This may involve transferring funds from the merchant account back to the cardholder account. Gateway sends a reply to the merchant system within the response document.

    On any steps merchant can check the transaction status sending CHECK request to Genome Gateway API.

  13. To encrypt a payment card data merchant can send TOKENIZE request to Genome Gateway API to encrypt credit card number and get the tokenized data.

Integration flow

Please, follow for the next flow:

  1. Sign up at my.genome.eu.

  2. Provide to support@genome.eu the list of required transaction types of your business model.

  3. Test all transaction types regarding your business model with XTS currency.

  4. Provide to support@genome.eu reference of test transactions in order to finish test integration.

  5. If test transactions are processed correctly, Genome's integration team will activate your account.

  6. Implement production credentials.

  7. Test production integration with all transaction types regarding your business model.

Host to host request formats

Test mode

Be advised: you can use any credit card or the cards listed below, as long as you use XTS in the currency field. XTS - is an ISO currency code reserved for use in testing. You can do test payments in the XTS currency even when your merchant account is already approved and LIVE.

Test credit cards

Card brand Supporting flow Card number CVV Expiry date
Visa 2D 4111111111111111 123 [3 digits random] MM - [from 01 to 12]; YYYY- 2020 or greater
Mastercard 2D 5555555555554444 123 [3 digits random] MM - [from 01 to 12]; YYYY- 2020 or greater
Visa 3D Secure 4012000300001003 123 [3 digits random] MM - [from 01 to 12]; YYYY- 2020 or greater
Mastercard 3D Secure 5191330000004415 123 [3 digits random] MM - [from 01 to 12]; YYYY- 2020 or greater

Be advised: test credit cards support the XTS currency only.

AUTH transaction

Sample code of the AUTH request in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "auth_request",
        "transaction_type": "AUTH",
        "amount": 9.99,
        "currency": "EUR",
        "card_number": "4111111111111111",
        "card_exp_month": "05",
        "card_exp_year": "2023",
        "cvv": "111",
        "first_name": "John",
        "last_name": "Doe",
        "card_holder": "John Doe",
        "address": "123 Street name.",
        "city": "New York",
        "state": "New York",
        "zip": "12100",
        "country": "USA",
        "user_phone": "+12025550000",
        "user_email": "johndoe@test.com",
        "user_ip": "127.0.0.1",
        "cof_type": "CIT-initial"
    }

Purpose: Interface is used to hold transaction amount on the card holder’s account with full payment card data.

Request parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes float
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant API login
merchant_password yes string (6-32) Merchant API password
transaction_unique_id yes string (11-45) Unique transaction Id
transaction_type yes string
Possible value: AUTH		 Type of the transaction: AUTH
amount yes float (0 - 9999999.9999) Amount of the transaction
currency yes string (3)
ISO 4217 (alfa-3)		 Currency of the transaction
card_number yes string (13-19 digits)
Luhn algorithm		 Number of the card
card_exp_month yes string (2 digits) Card expiration month. Month number from '01' to '12'
card_exp_year yes string (4 digits) Card expiration year
cvv conditional string (3-4 digits) Card Verification Value
card_holder yes string (2-32) Cardholder name
first_name yes string (1-32) The first name of the customer
last_name yes string (1-32) The last name of the customer
address conditional string (2-64) Customer's address
city conditional string (2-32) Customer's city
state conditional string (1-32) Customer's state
zip conditional string (2-10) Customer's zip
country yes string (3)
ISO 3166-1 alpha-3		 Customer's country
user_phone conditional string (7-15) Customer's phone number. For testmode the value should be passed with + symbol
user_email yes string (6-255) Customer's email address
user_ip yes string (IPv4, IPv6) Customer's IP address. Not all acquirers support IPv6 format
merchant_user_id optional string (0-32) User Id on merchant's side
merchant_domain_name optional string (0-255) Merchant's domain name
merchant_affiliate_id optional string (0-255) Affiliate identifier
merchant_product_name optional string (0-255) Name of the product
descriptor_merchant optional string (0-255) Descriptor of the merchant
descriptor_phone optional string (0-255) Descriptor phone of the merchant
mid_reference optional string (16) Reference of the MID in Genome system
date_of_birth optional string (YYYY-MM-DD) Date of birth of the customer
cof_type optional enum('CIT-initial', 'CIT-subsequent', 'MIT') The credentials on file(COF) is used to identify authorization requests that use stored credentials for a consumer, in order to improve authorization rates and reduce fraud. 'CIT-initial' - First transactions initiated by customer on your service (e.g. trial product, first subscription, one-time purchase etc.) 'CIT-subsequent' - Subsequent transactions initiated by customer (e.g. one-clicks, cross-sales). 'MIT' - Transactions initiated by merchant (e. g. rebill).

Be advised: In most cases conditional parameters are required for acquirers.

Be advised: for test mode add a plus symbol for a phone value. Otherwise a transaction will be declined with reason GENERAL BANK DECLINE.

Be advised: Supporting of this transaction type depends on acquirer side. Please, clarify the information before implementation of this transaction type.

Sample code of the AUTH response in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "sessionid": "543e2136-d46c-4d7d-a3b3-075cf9adkl01",
        "transaction_unique_id": "auth_request",
        "token": "5524fa52-75d8-4c7a-84ec-039d3097ab6f",
        "reference": "ATFF0000000039FDAEEF",
        "timestamp": 1608001694,
        "authcode": "authcode_1544565466.22",
        "status": "success",
        "code": 0,
        "message": "Transaction processed successfully"
    }

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
api_version float
Possible value: 1		 API version
merchant_account string (6-32) Merchant API login
sessionid string (36) Id of the session
transaction_unique_id string (11-45) Unique transaction Id
token string (36) Hashed value of card number, expiry date and cardholder name
reference string (20) Reference of the transaction in Genome system
timestamp integer (unix timestamp) Timestamp of the transaction
authcode string or null (0-24) Authorization code
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result

After the AUTH transaction has been processed a merchant have to send the following transactions: * SETTLE * VOID * CHECK

AUTH (by token) transaction

Sample code of the AUTH (by token) request in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "merchant_password",
        "transaction_unique_id": "auth_by_token_request",
        "transaction_type": "AUTH",
        "amount": 9.99,
        "currency": "EUR",
        "first_name": "John",
        "last_name": "Doe",
        "card_holder": "John Doe",
        "address": "123 Street name.",
        "city": "New York",
        "state": "New York",
        "zip": "12100",
        "country": "USA",
        "user_phone": "+12025550000",
        "user_email": "johndoe@test.com",
        "user_ip": "127.0.0.1",
        "token": "5524fa52-75d8-4c7a-84ec-039d3097ab6f",
        "cof_type": "CIT-initial"
    }

Purpose: Interface is used to hold transaction amount on the card account using billtoken.

Request parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes float
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant API login
merchant_password yes string (6-32) Merchant API password
transaction_unique_id yes string (11-45) Unique transaction Id
transaction_type yes string
Possible value: AUTH		 Type of the transaction: AUTH
amount yes float (0 - 9999999.9999) Amount of the transaction
currency yes string (3)
ISO 4217 (alfa-3)		 Currency of the transaction
token yes string (36) Hashed value of card number, expiry date and cardholder name
card_holder yes string (2-32) Cardholder name
first_name yes string (1-32) The first name of the customer
last_name yes string (1-32) The last name of the customer
address conditional string (2-64) Customer's address
city conditional string (2-32) Customer's city
state conditional string (1-32) Customer's state
zip conditional string (2-10) Customer's zip
country yes string (3)
ISO 3166-1 alpha-3		 Customer's country
user_phone conditional string (7-15) Customer's phone number. For testmode the value should be passed with + symbol
user_email yes string (6-255) Customer's email address
user_ip yes string (IPv4, IPv6) Customer's IP address. Not all acquirers support IPv6 format
merchant_user_id optional string (0-32) User Id on merchant's side
merchant_domain_name optional string (0-255) Merchant's domain name
merchant_affiliate_id optional string (0-255) Affiliate identifier
merchant_product_name optional string (0-255) Name of the product
descriptor_merchant optional string (0-255) Descriptor of the merchant
descriptor_phone optional string (0-255) Descriptor phone of the merchant
mid_reference optional string (16) Reference of the MID in Genome system
date_of_birth optional string (YYYY-MM-DD) Date of birth of the customer
cof_type optional enum('CIT-initial', 'CIT-subsequent', 'MIT') The credentials on file(COF) is used to identify authorization requests that use stored credentials for a consumer, in order to improve authorization rates and reduce fraud. 'CIT-initial' - First transactions initiated by customer on your service (e.g. trial product, first subscription, one-time purchase etc.) 'CIT-subsequent' - Subsequent transactions initiated by customer (e.g. one-clicks, cross-sales). 'MIT' - Transactions initiated by merchant (e. g. rebill).

Be advised: In most cases conditional parameters are required for acquirers.

Be advised: if merchant use a scheme AUTH3D + AUTH + SETTLE, then for AUTH request merchant should also add a PARes value.

Be advised: for test mode add a plus symbol for a phone value. Otherwise a transaction will be declined with reason GENERAL BANK DECLINE.

Be advised: Supporting of this transaction type depends on acquirer side. Please, clarify the information before implementation of this transaction type.

Sample code of AUTH (by token) response in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "sessionid": "543e2136-d46c-4d7d-a3b3-075cf9af6dea",
        "transaction_unique_id": "auth_by_token_request",
        "token": "5524fa52-75d8-4c7a-84ec-039d3097ab6f",
        "reference": "ATFF0000000039FDA11F",
        "timestamp": 1618001694,
        "authcode": "authcode_1518565221.44",
        "status": "decline",
        "code": 3100,
        "message": "General bank decline"
    }

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
api_version float
Possible value: 1		 API version
merchant_account string (6-32) Merchant API login
sessionid string (36) Id of the session
transaction_unique_id string (11-45) Unique transaction Id
token string (36) Hashed value of card number, expiry date and cardholder name
reference string (20) Reference of the transaction in Genome system
timestamp integer (unix timestamp) Timestamp of the transaction
authcode string or null (0-24) Authorization code
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result

After the AUTH (by token) transaction has been processed a merchant depending on business requirements has ability but not forced to send the following transactions: * SETTLE * VOID * CHECK

SETTLE transaction

Sample code of the SETTLE request in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "settle_request",
        "transaction_type": "SETTLE",
        "amount": 9.99,
        "currency": "EUR",
        "reference": "ATFF0000000039FDA11F"
    }

Purpose: Interface is used to settle a previously-authorized (using AUTH) transaction.

Request parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes float
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant API login
merchant_password yes string (6-32) Merchant API password
transaction_unique_id yes string (11-45) Unique transaction Id
transaction_type yes string
Possible value: SETTLE		 Type of the transaction: SETTLE
amount yes float (0 - 9999999.9999) Amount of the transaction
currency yes string (3)
ISO 4217 (alfa-3)		 Currency of the transaction
reference yes string (20) Reference of the base transation (AUTH)
merchant_user_id optional string (0-32) User Id on merchant's side
merchant_domain_name optional string (0-255) Merchant's domain name
merchant_affiliate_id optional string (0-255) Affiliate identifier
merchant_product_name optional string (0-255) Name of the product
descriptor_merchant optional string (0-255) Descriptor of the merchant
descriptor_phone optional string (0-255) Descriptor phone of the merchant

Be advised: for test mode add a plus symbol for a phone value. Otherwise a transaction will be declined with reason GENERAL BANK DECLINE.

Be advised: Supporting of this transaction type depends on acquirer side. Please, clarify the information before implementation of this transaction type.

Sample code of the SETTLE response in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "sessionid": "543e2136-d46c-4d7d-a3b3-075cf9adkl21",
        "transaction_unique_id": "settle_request",
        "token": "5524fa52-75d8-4c7a-84ec-039d3097ab6f",
        "reference": "STFF0000000039FDAEGG",
        "timestamp": 1408001694,
        "authcode": "",
        "status": "success",
        "code": 0,
        "message": "Transaction processed successfully"
    }

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
api_version float
Possible value: 1		 API version
merchant_account string (6-32) Merchant API login
sessionid string (36) Id of the session
transaction_unique_id string (11-45) Unique transaction Id
token string (36) Hashed value of card number, expiry date and cardholder name
reference string (20) Reference of the transaction in Genome system
timestamp integer (unix timestamp) Timestamp of the transaction
authcode string or null (0-24) Authorization code
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result

After the SETTLE transaction has been processed a merchant depending on business requirements has ability but not forced to send the following transactons: * VOID (depends on acquirer side) * REFUND * CHECK

SALE3D transaction

Sample code of the SALE3D request in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "sale3d_request",
        "transaction_type": "SALE3D",
        "amount": 10,
        "currency": "USD",
        "card_number": "5191330000004415",
        "card_exp_month": "05",
        "card_exp_year": "2023",
        "cvv": "121",
        "first_name": "John",
        "last_name": "Doe",
        "card_holder": "John Doe",
        "address": "123 Street name.",
        "city": "New York",
        "state":"New York",
        "zip": "12100",
        "country": "USA",
        "user_phone": "+12025550000",
        "user_email": "johndoe@test.com",
        "user_ip": "127.0.0.1",
        "callback_url": "https://merchant.com/callback",
        "redirect_url": "https://merchant.com/redirect",
        "cof_type": "CIT-initial"
    }

Purpose: Interface is used to check ability to follow 3DS flow for the card. The ECI code will be returned to explain the reason (for example in negative case). In the positive case SALE request runs automatically on Genome Gateway side. Response on SALE request will be transmitted to Merchant callback URL.

Request parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes float
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant API login
merchant_password yes string (6-32) Merchant API password
transaction_unique_id yes string (11-45) Unique transaction Id
transaction_type yes string
Possible value: SALE3D		 Type of the transaction: SALE3D
amount yes float (0 - 9999999.9999) Amount of the transaction
currency yes string (3)
ISO 4217 (alfa-3)		 Currency of the transaction
card_number yes string (13-19 digits)
Luhn algorithm		 Number of the card
card_exp_month yes string (2 digits) Card expiration month. Month number from '01' to '12'
card_exp_year yes string (4 digits) Card expiration year
cvv conditional string (3-4 digits) Card Verification Value
card_holder yes string (2-32) Cardholder name
first_name yes string (1-32) The first name of the customer
last_name yes string (1-32) The last name of the customer
address conditional string (2-64) Customer's address
city conditional string (2-32) Customer's city
state conditional string (1-32) Customer's state
zip conditional string (2-10) Customer's zip
country yes string (3)
ISO 3166-1 alpha-3		 Customer's country
user_phone conditional string (7-15) Customer's phone number. For testmode the value should be passed with + symbol
user_email yes string (6-255) Customer's email address
user_ip yes string (IPv4, IPv6) Customer's IP address. Not all acquirers support IPv6 format
callback_url yes Not Empty String
https required		 Once the order has been processed merchant will receive a final response (callback) regarding the transaction status to this URL
redirect_url yes Not Empty String
https required		 Once the verification process has been done a customer will be redirected to this URL
merchant_user_id optional string (0-32) User Id on merchant's side
merchant_domain_name optional string (0-255) Merchant's domain name
merchant_affiliate_id optional string (0-255) Affiliate identifier
merchant_product_name optional string (0-255) Name of the product
descriptor_merchant optional string (0-255) Descriptor of the merchant
descriptor_phone optional string (0-255) Descriptor phone of the merchant
mid_reference optional string (16) Reference of the MID in Genome system
date_of_birth optional string (YYYY-MM-DD) Date of birth of the customer
cof_type optional enum('CIT-initial', 'CIT-subsequent', 'MIT') The credentials on file(COF) is used to identify authorization requests that use stored credentials for a consumer, in order to improve authorization rates and reduce fraud. 'CIT-initial' - First transactions initiated by customer on your service (e.g. trial product, first subscription, one-time purchase etc.) 'CIT-subsequent' - Subsequent transactions initiated by customer (e.g. one-clicks, cross-sales). 'MIT' - Transactions initiated by merchant (e. g. rebill).

Be advised: In most cases conditional parameters are required for acquirers.

Be advised: for test mode add a plus symbol for a phone value. Otherwise a transaction will be declined with reason GENERAL BANK DECLINE.

Be advised: Supporting of this transaction type depends on acquirer side. Please, clarify the information before implementation of this transaction type.

Sample code of the SALE3D response in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "sessionid": "543e2136-d46c-4d7d-a3b3-075cf9adkl21",
        "transaction_unique_id": "sale3d_request",
        "token": "5524fa52-75d8-4c7a-84ec-039d3097ab6g",
        "reference": "S3FF0000000039FDAEGG",
        "timestamp": 1638001694,
        "authcode": "",
        "eci": 5,
        "acs_url": "https://acs.bank.com/authentication",
        "authcode": "",
        "status": "success",
        "code": 0,
        "message": "Transaction processed successfully"
    }

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
api_version float
Possible value: 1		 API version
merchant_account string (6-32) Merchant API login
sessionid string (36) Id of the session
transaction_unique_id string (11-45) Unique transaction Id
token string (36) Hashed value of card number, expiry date and cardholder name
reference string (20) Reference of the transaction in Genome system
timestamp integer (unix timestamp) Timestamp of the transaction
authcode string or null (0-24) Authorization code
acs_url string or null (0-255) Access Control Server (ACS). Parameter may not be received
eci float
Possible values: 1, 2, 5, 6, 7		 Electronic Commerce Indicators (ECI). Parameter may not be received
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result

Callback

Sample code of the callback request for SALE3D transaction in "application/x-www-form-urlencoded" format:


    token=5aaaa194-1d68-4ef8-a72f-009184ee03a6
    &reference=PTFF00000000396580CF
    &transaction_unique_id=payout_0716100000
    &status=success
    &code=0
    &message=Transaction processed successfully
    &checkSum=4804928393234a6cd05f177569147091d7138da25fc61d9ee5add357017239a6

Callback is a final response for SALE3D transaction regarding the status of the transaction. According to SALE3D flow Genome initiates SALE transaction automatically and sends the response to predefined Merchant callback URL. Parameters of callback fields are provided below:

PARAMETER NAME FORMAT and RULE DESCRIPTION
token string (36) Hashed value of card number, expiry date and cardholder name
reference string (20) Reference of the transaction in Genome system
transaction_unique_id string (11-45) Unique transaction Id
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result
checkSum string (64) Signature for callback parameters

Callback is received to a merchant when in response Genome got the code - 200 and body text - OK. In other cases, callback is not received and Genome will try periodically to send callback data. The number of attempts are limited.

Be advised, that Genome can resend a few times callbacks for one transaction. It depends by acquirer bank side.

Examples below describe different cases with callback data receiving:

HTTP Code Body text Description
200 OK Callback is successfully received
500 OK Callback is not received

After the SALE3D transaction has been processed a merchant depending on business requirements has ability to send the following transactons: * REFUND * CHECK

checkSum calculation

checkSum calculation allows to compare value of the checkSum in callback request with own calculation.

PHP algorithm below shows the calculation logic of “checkSum”:


    <?php

        // Example of the callback request to merchant, application/x-www-form-urlencoded format.
        $callbackData = 'token=5aaaa194-1d68-4ef8-a72f-009184ee03a6&reference=PTFF00000000396580CF&transaction_unique_id=payout_0716100000&status=success&code=0&message=Transaction processed successfully&checkSum=4804928393234a6cd05f177569147091d7138da25fc61d9ee5add357017239a6';

        // Example of the sorted parameters. Also, private key, provided by Genome is added in the end of the line.
        $sortedData = 'code=0|message=Transaction processed successfully|reference=PTFF00000000396580CF|status=success|token=5aaaa194-1d68-4ef8-a72f-009184ee03a6|transaction_unique_id=payout_0716100000|your_private_key';

        // Getting the result of checkSum calculation
        $countedCheckSum = hash('sha256', $sortedData);

    ?>

If you need to calculate and compare the value checkSum callback, use the algorithm described below:

Please note, that all the callback values are counted in the calculation of the checkSum parameter.

Please note, that a value of the your_privat_signature is your API password. You can later access it at Merchants tab -> Technical details section at my.genome.eu.

If fully translate callback shown in the example into the line we get:

SALE transaction

Sample code of the SALE request in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "sale_request",
        "transaction_type": "SALE",
        "amount": 9.99,
        "currency": "EUR",
        "card_number": "4111111111111111",
        "card_exp_month": "09",
        "card_exp_year": "2023",
        "cvv": "121",
        "first_name": "John",
        "last_name": "Doe",
        "card_holder": "John Doe",
        "address": "123 Street name.",
        "city": "New York",
        "state": "New York",
        "zip": "12100",
        "country": "USA",
        "user_phone": "+12025550000",
        "user_email": "johndoe@test.com",
        "user_ip": "127.0.0.1",
        "cof_type": "CIT-initial"
    }

Purpose: Interface is used to collect money directly from cardholder account using full payment card data.

Please note that in case of 3ds flow (after AUTH3D has successfully processed) pares and reference fields should be Required transmitted in the request.

Request parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes float
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant API login
merchant_password yes string (6-32) Merchant API password
transaction_unique_id yes string (11-45) Unique transaction Id
transaction_type yes string
Possible value: SALE		 Type of the transaction: SALE
amount yes float (0 - 9999999.9999) Amount of the transaction
currency yes string (3)
ISO 4217 (alfa-3)		 Currency of the transaction
card_number yes string (13-19 digits)
Luhn algorithm		 Number of the card
card_exp_month yes string (2 digits) Card expiration month. Month number from '01' to '12'
card_exp_year yes string (4 digits) Card expiration year
cvv conditional string (3-4 digits) Card Verification Value
card_holder yes string (2-32) Cardholder name
first_name yes string (1-32) The first name of the customer
last_name yes string (1-32) The last name of the customer
address conditional string (2-64) Customer's address
city conditional string (2-32) Customer's city
state conditional string (1-32) Customer's state
zip conditional string (2-10) Customer's zip
country yes string (3)
ISO 3166-1 alpha-3		 Customer's country
user_phone conditional string (7-15) Customer's phone number. For testmode the value should be passed with + symbol
user_email yes string (6-255) Customer's email address
user_ip yes string (IPv4, IPv6) Customer's IP address. Not all acquirers support IPv6 format
merchant_user_id optional string (0-32) User Id on merchant's side
merchant_domain_name optional string (0-255) Merchant's domain name
merchant_affiliate_id optional string (0-255) Affiliate identifier
merchant_product_name optional string (0-255) Name of the product
descriptor_merchant optional string (0-255) Descriptor of the merchant
descriptor_phone optional string (0-255) Descriptor phone of the merchant
mid_reference optional string (16) Reference of the MID in Genome system
date_of_birth optional string (YYYY-MM-DD) Date of birth of the customer
cof_type optional enum('CIT-initial', 'CIT-subsequent', 'MIT') The credentials on file(COF) is used to identify authorization requests that use stored credentials for a consumer, in order to improve authorization rates and reduce fraud. 'CIT-initial' - First transactions initiated by customer on your service (e.g. trial product, first subscription, one-time purchase etc.) 'CIT-subsequent' - Subsequent transactions initiated by customer (e.g. one-clicks, cross-sales). 'MIT' - Transactions initiated by merchant (e. g. rebill).

Be advised: In most cases conditional parameters are required for acquirers.

Be advised: for test mode add a plus symbol for a phone value. Otherwise a transaction will be declined with reason GENERAL BANK DECLINE.

Sample code of the SALE response in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "sessionid": "543e2136-d46c-4d7d-a3b3-075cf9adkl01",
        "transaction_unique_id": "sale_request",
        "token": "5524fa52-75d8-4c7a-84ec-039d3097ab6f",
        "reference": "SLFF0000000039FDAEAB",
        "timestamp": 1618001694,
        "authcode": "",
        "status": "success",
        "code": 0,
        "message": "Transaction processed successfully"
    }

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
api_version float
Possible value: 1		 API version
merchant_account string (6-32) Merchant API login
sessionid string (36) Id of the session
transaction_unique_id string (11-45) Unique transaction Id
token string (36) Hashed value of card number, expiry date and cardholder name
reference string (20) Reference of the transaction in Genome system
timestamp integer (unix timestamp) Timestamp of the transaction
authcode string or null (0-24) Authorization code
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result

After the SALE transaction has been processed a merchant depending on business requirements has ability but not forced to send the following transactons: * SALE by token * REFUND * CHECK

SALE (by token) transaction

Sample code of the SALE (by token) request in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "sale_by_token_request",
        "transaction_type": "SALE",
        "amount": 9.99,
        "currency": "EUR",
        "first_name": "John",
        "last_name": "Doe",
        "card_holder": "John Doe",
        "address": "123 Street name.",
        "city": "New York",
        "state": "New York",
        "zip": "12100",
        "country": "USA",
        "user_phone": "+12025550000",
        "user_email": "johndoe@test.com",
        "user_ip": "127.0.0.1",
        "token": "5524fa52-75d8-4c7a-84ec-039d-97ab6f",
        "cof_type": "MIT"
    }

Purpose: Interface is used to collect money directly from cardholder account using billtoken value.

Request parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes float
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant API login
merchant_password yes string (6-32) Merchant API password
transaction_unique_id yes string (11-45) Unique transaction Id
transaction_type yes string
Possible value: SALE		 Type of the transaction: SALE
amount yes float (0 - 9999999.9999) Amount of the transaction
currency yes string (3)
ISO 4217 (alfa-3)		 Currency of the transaction
token yes string (36) Hashed value of card number, expiry date and cardholder name
card_holder yes string (2-32) Cardholder name
first_name yes string (1-32) The first name of the customer
last_name yes string (1-32) The last name of the customer
address conditional string (2-64) Customer's address
city conditional string (2-32) Customer's city
state conditional string (1-32) Customer's state
zip conditional string (2-10) Customer's zip
country yes string (3)
ISO 3166-1 alpha-3		 Customer's country
user_phone conditional string (7-15) Customer's phone number. For testmode the value should be passed with + symbol
user_email yes string (6-255) Customer's email address
user_ip yes string (IPv4, IPv6) Customer's IP address. Not all acquirers support IPv6 format
merchant_user_id optional string (0-32) User Id on merchant's side
merchant_domain_name optional string (0-255) Merchant's domain name
merchant_affiliate_id optional string (0-255) Affiliate identifier
merchant_product_name optional string (0-255) Name of the product
descriptor_merchant optional string (0-255) Descriptor of the merchant
descriptor_phone optional string (0-255) Descriptor phone of the merchant
mid_reference optional string (16) Reference of the MID in Genome system
date_of_birth optional string (YYYY-MM-DD) Date of birth of the customer
cof_type optional enum('CIT-initial', 'CIT-subsequent', 'MIT') The credentials on file(COF) is used to identify authorization requests that use stored credentials for a consumer, in order to improve authorization rates and reduce fraud. 'CIT-initial' - First transactions initiated by customer on your service (e.g. trial product, first subscription, one-time purchase etc.) 'CIT-subsequent' - Subsequent transactions initiated by customer (e.g. one-clicks, cross-sales). 'MIT' - Transactions initiated by merchant (e. g. rebill).

Be advised: for test mode add a plus symbol for a phone value. Otherwise a transaction will be declined with reason GENERAL BANK DECLINE.

Sample code of the SALE (by token) response in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "sessionid": "543e2136-d46c-4d7d-a3b3-075cf9adkl21",
        "transaction_unique_id": "sale_by_token_request",
        "token": "5524fa52-75d8-4c7a-84ec-039d3097ab6f",
        "reference": "SLFF0000000039FDAEGG",
        "timestamp": 1628001612,
        "authcode": "",
        "status": "success",
        "code": 0,
        "message": "Transaction processed successfully"
    }

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
api_version float
Possible value: 1		 API version
merchant_account string (6-32) Merchant API login
sessionid string (36) Id of the session
transaction_unique_id string (11-45) Unique transaction Id
token string (36) Hashed value of card number, expiry date and cardholder name
reference string (20) Reference of the transaction in Genome system
timestamp integer (unix timestamp) Timestamp of the transaction
authcode string or null (0-24) Authorization code
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result

After the SALE (by token) transaction has been processed a merchant depending on business requirements has ability but not forced to send the following transactons: * REFUND * CHECK

REFUND transaction

Sample code of the REFUND request in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "refund_request",
        "transaction_type": "REFUND",
        "amount": 9.99,
        "currency": "EUR",
        "reference": "SLFF0000000039FDAEAW"
    }

Purpose: Interface is used to refund a previously settled transaction.

Request parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes float
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant API login
merchant_password yes string (6-32) Merchant API password
transaction_unique_id yes string (11-45) Unique transaction Id
transaction_type yes string
Possible value: REFUND		 Type of the transaction: REFUND
amount yes float (0 - 9999999.9999) Amount of the transaction
currency yes string (3)
ISO 4217 (alfa-3)		 Currency of the transaction
reference yes string (20) Reference of the base transation (SALE, SALE3D, SETTLE)
merchant_user_id optional string (0-32) User Id on merchant's side
descriptor_merchant optional string (0-255) Descriptor of the merchant
descriptor_phone optional string (0-255) Descriptor phone of the merchant

Sample code of the REFUND response in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "sessionid": "543e2136-d46c-4d7d-a3b3-075cf9adkl21",
        "transaction_unique_id": "refund_request",
        "token": "5524fa52-75d8-4c7a-84ec-039d3097ab6f",
        "reference": "RFF0000000039FDAEGG",
        "timestamp": 1614001691,
        "authcode": "",
        "status": "success",
        "code": 0,
        "message": "Transaction processed successfully"
    }

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
api_version float
Possible value: 1		 API version
merchant_account string (6-32) Merchant API login
sessionid string (36) Id of the session
transaction_unique_id string (11-45) Unique transaction Id
token string (36) Hashed value of card number, expiry date and cardholder name
reference string (20) Reference of the transaction in Genome system
timestamp integer (unix timestamp) Timestamp of the transaction
authcode string or null (0-24) Authorization code
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result

After the REFUND transaction has been processed a merchant depending on business requirements has ability but not forced to send the following transactons: * CHECK

VOID transaction

Sample code of the VOID request in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_unique_id": "void_request",
        "transaction_type": "VOID",
        "reference": "ATFF0000000039FDAEAQ"
    }

Purpose: Interface is used to to back out of a transaction before it is settled or credited.

Request parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes float
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant API login
merchant_password yes string (6-32) Merchant API password
transaction_unique_id yes string (11-45) Unique transaction Id
transaction_type yes string
Possible value: VOID		 Type of the transaction: VOID
reference yes string (20) Reference of the base transation (AUTH or AUTH3D)
merchant_user_id optional string (0-32) User Id on merchant's side
descriptor_merchant optional string (0-255) Descriptor of the merchant
descriptor_phone optional string (0-255) Descriptor phone of the merchant

Be advised: Supporting of this transaction type depends on acquirer side. Please, clarify the information before implementation of this transaction type.

Sample code of the VOID response in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "sessionid": "543e2136-d46c-4d7d-a3b3-075cf9adkl21",
        "transaction_unique_id": "void_request001",
        "token": "5524fa52-75d8-4c7a-84ec-039d3097ab6f",
        "reference": "VDFF0000000039FDAEGG",
        "timestamp": 1601001621,
        "authcode": "",
        "status": "success",
        "code": 0,
        "message": "Transaction processed successfully"
    }

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
api_version float
Possible value: 1		 API version
merchant_account string (6-32) Merchant API login
sessionid string (36) Id of the session
transaction_unique_id string (11-45) Unique transaction Id
token string (36) Hashed value of card number, expiry date and cardholder name
reference string (20) Reference of the transaction in Genome system
timestamp integer (unix timestamp) Timestamp of the transaction
authcode string or null (0-24) Authorization code
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result

After the VOID transaction has been processed a merchant depending on business requirements has ability but not forced to send the following transactons: * CHECK

CHECK transaction

Sample code of the CHECK request in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "merchant_password": "password123",
        "transaction_type": "CHECK",
        "reference": "ATFF00000000395AD690",
        "transaction_unique_id": "check_request"
    }

Purpose: Interface should be used to check transaction status.

Request parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes float
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant API login
merchant_password yes string (6-32) Merchant API password
transaction_type yes string
Possible value: CHECK		 Type of the transaction: CHECK
transaction_unique_id conditional string (11-45) Unique transaction Id
reference conditional string (20) Reference of the transation to check

transaction_unique_id or reference can be passed for CHECK request.

Sample code of the CHECK response in "application/json" format:

    {
        "api_version": 1,
        "merchant_account": "Account_MP_TRX",
        "sessionid": "5668fbfb-2d9c-492c-9f7c-11fb8ae9e3fc",
        "transactions": [
            {
                "reference": "ATFF00000000395AD690",
                "transaction_unique_id": "check_request",
                "transaction_type": "AUTH",
                "status": "SUCCESS",
                "code": 0,
                "message": "SUCCESS",
                "token": "5519225d-3460-433f-ad4e-62649d0bb909",
                "timestamp": 1529796980,
                "authcode": "111313"
            }
        ],
        "status": "success",
        "code": 0,
        "message": "Transaction processed successfully"
    }

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
api_version float
Possible value: 1		 API version
merchant_account string (6-32) Merchant API login
sessionid string (36) Id of the session
transactions array Contains of transaction data array
reference string (20) Reference of the transaction in Genome system
transaction_unique_id string (11-45) Unique transaction Id
transaction_type string
Possible values: AUTH3D, AUTH, SALE3D, SALE, VOID, REFUND		 Type of the transaction
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result
token string (36) Hashed value of card number, expiry date and cardholder name
timestamp integer (unix timestamp) Timestamp of the transaction
authcode string or null (0-24) Authorization code
transactions end of the array ** -//- **
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result

After the CHECK transaction has been processed merchant can send any transactons depending on the stage of an actual transaction flow process.

Custom parameters

Additional custom parameters (request):

Purpose: Own custom parameters also could be sent via API. For more information please contact support@genome.eu

Additional custom parameters (response/callback):

Purpose: Custom parameters can be added to the response. For activation please send a query to support@genome.eu.

NAME OF THE PARAMETER SEND TO MERCHANT RULES DESCRIPTION
Bank descriptor custom_bank_descriptor /.{0,255}/ Descriptor of the acquirer
Bank advice custom_bank_advice /.{0,65535}/ Advice by the acquirer
Bank Id custom_bank_id /\d{1,20}/ Id of the acquirer
Bank name custom_bank_name /.{0,32}/ Name of the acquirer
Bank reason code custom_bank_reason_code /.{0,45}/ Reason code of the acquirer
Bank reason description custom_bank_reason_description /.{0,200}/ Acquirer reason description
Bank transaction id custom_bank_transaction_id /.{0,255}/ Transaction Id by bank
Bank user address custom_bank_user_address /.{0,255}/ User address by bank
Bank user city custom_bank_user_city /.{0,255}/ User city by bank
Bank user country custom_bank_user_country /.{0,255}/ User country by bank
Bank user first name custom_bank_user_first_name /.{0,255}/ User first name by bank
Bank user Id custom_bank_user_id /.{0,255}/ User Id by bank
Bank user lastname custom_bank_user_last_name /.{0,255}/ User last name by bank
Card bank custom_card_bank /.{0,255}/ Bank issuer
Card bin custom_card_bin /\d{6}/ Bin of the card
Card brand custom_card_brand /.{0,255}/ Brand of the card
Cardholder custom_card_cardholder /.{0,255}/ Cardholder name
Card country custom_card_country /.{0,255}/ Card country
Card country ISO3 custom_card_country_iso3 /.{3}/ Card country ISO3 format
Card hash custom_card_hash /.{0,255}/ Hash of the credit card
Card last custom_card_last /\d{4}/ The last 4 digits of the credit card
Card month custom_card_month /\d{2}/ Expiration month of the credit card
Card year custom_card_year /\d{2}/ Expiration year of the credit card
Chargeback base amount custom_chargeback_base_amount /\d{1,14}.\d{1,6}/ Amount of the base transaction
Chargeback base amount CNY custom_chargeback_base_amount_cny /\d+(.\d{1,4})?/ Amount of the base transaction in CNY
Chargeback base amount EUR custom_chargeback_base_amount_eur /\d+(.\d{1,4})?/ Amount of the base transaction in EUR
Chargeback base amount GBP custom_chargeback_base_amount_gbp /\d+(.\d{1,4})?/ Amount of the base transaction in GBP
Chargeback base amount UAH custom_chargeback_base_amount_uah /\d+(.\d{1,4})?/ Amount of the base transaction in UAH
Chargeback base amount USD custom_chargeback_base_amount_usd /\d+(.\d{1,4})?/ Amount of the base transaction in USD
Chargeback base currency custom_chargeback_base_currency /.{1,10}/ Currency of the base transaction
Descriptor merchant custom_descriptor_merchant /\d+(.\d{1,4})?/ Descriptor
Descriptor phone custom_descriptor_phone /\d+(.\d{1,4})?/ Descriptor phone
Fee EUR custom_fee_eur /\d+(.\d{1,4})?/ Fee in EUR
Fee GBP custom_fee_gbp /\d+(.\d{1,4})?/ Fee in GBP
Fee info custom_fee_info /.{0,65535}/ Information regarding fee
Fee rolling reserve custom_fee_rolling_reserve /\d+(.\d{1,4})?/ Rolling reserve fee
Fee UAH custom_fee_uah /\d+(.\d{1,4})?/ Fee in UAH
Fee USD custom_fee_usd /\d+(.\d{1,4})?/ Fee in USD
Fraud action custom_fraud_action /.{0,255}/ Fraud action
Fraud decision custom_fraud_decision /accept or reject or manual/ Fraud decision
fraud reject reason custom_fraud_reject_reason /.{0,65535}/ Reject reason by fraud
Fraud score custom_fraud_score /\d{1,9}/ Fraud score by user
MID id custom_mid_id /\d{1,20}/ Id of the MID
MID name custom_mid_name /.{0,64}/ Name of the MID
MID reference custom_mid_reference /MD[0-9A-F]{14}/ Reference of the MID
Next billing date custom_next_billing_date /\d{8,}/ Next billing date
Payment account id custom_payment_account_id /\d{1,20}/ Account Id
Secure storage id secure_storage_id /.{0,45}/ Hashed value of the PAN
User first name custom_user_first_name /.{0,255}/ The first name of the user
User last name custom_user_last_name /.{0,255}/ The last name of the user
User phone custom_user_phone /.{0,255}/ Phone of the user

Validation exposition: MDN web docs

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:

Payment Page

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="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>

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.
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_ String OPTIONAL Any custom parameters should start with 'custom_' prefix.

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.

String should be formated using | separator in this way:

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

Code example JSON:

{
  "is_test" : false,
  "api_key" : "MBg90FSSnwySJ5MKvGARHVdtWuslsqpvVz4pUTSOPCMhqkHV48PhGPK6WR9iCr6n",
  "signature" : "7e00f76fd75f1ba9a52b9b8fb61d003dd0d033bfadbdd15d07cef99b45428aa7",
  "session_id" : "hYLT7rq88sPCH92bUGs4Tdjd3wUU1ohPa47kXWhlcAZpBcDJa56ov41e0qRQAzJQ",
  "transaction_id" : 5587848,
  "transaction_status" : "SUCCESS",
  "transaction_error_code" : 0,
  "transaction_timestamp" : 1647780071,
  "card_token" : null,
  "bill_token" : "62065b8d-589c-4f00-8f1f-3fcf5d12f1cb",
  "payment_method_type" : "CC",
  "amount" : 15.00,
  "currency_iso" : "EUR",
  "order_id" : "891544ML",
  "user_id" : "565",
  "custom" : {
    "custom_user_phone" : "+37052141409",
    "custom_device_fingerprint" : "myAwesomeDeviceFingerprint",
    "custom_merchant_affiliate_id" : "myAwesomeAffiliate_id-789369",
    "custom_merchant_product_name" : "myAwesomeProductName",
    "custom_merchant_domain_name" : "myAwesomeDomain"
  }
}

Code example XML:

<callback>
  <is_test>false</is_test>
  <api_key>MBg90FSSnwySJ5MKvGARHVdtWuslsqpvVz4pUTSOPCMhqkHV48PhGPK6WR9iCr6n</api_key>
  <signature>6ec5f32e5749bf6df4077de9f9e7f9bccba0ecb5b88c4107aabe5d0a1bdba14a</signature>
  <session_id>GoZLYBqWiCL9FBcVMjIVn8VEso1pgoIoGF91YG1Uzyw83AQNxQ53hQRgaGd3JpLw</session_id>
  <transaction_id>5587851</transaction_id>
  <transaction_status>SUCCESS</transaction_status>
  <transaction_error_code>0</transaction_error_code>
  <transaction_timestamp>1647780836</transaction_timestamp>
  <card_token/>
  <bill_token>62065b8d-589c-4f00-8f1f-3fcf5d12f1cb</bill_token>
  <payment_method_type>CC</payment_method_type>
  <amount>15.00</amount>
  <currency_iso>EUR</currency_iso>
  <order_id>891544ML</order_id>
  <user_id>565</user_id>
  <custom>
    <custom_user_phone>+37052141409</custom_user_phone>
    <custom_device_fingerprint>myAwesomeDeviceFingerprint</custom_device_fingerprint>
    <custom_merchant_affiliate_id>myAwesomeAffiliate_id-789369</custom_merchant_affiliate_id>
    <custom_merchant_product_name>myAwesomeProductName</custom_merchant_product_name>
    <custom_merchant_domain_name>myAwesomeDomain</custom_merchant_domain_name>
  </custom>
</callback>

Code example YAML:

is_test: false
api_key: "MBg90FSSnwySJ5MKvGARHVdtWuslsqpvVz4pUTSOPCMhqkHV48PhGPK6WR9iCr6n"
signature: "3e5a9d7f10dfda47dc5c8ca98301e08ef191e937d86d1b426714ac49c4b33357"
session_id: "RvOPt0OGqRP4s72Imbra4IFvFFMM7UnFTQaz67A8UCOxNHXPUFb3DKItMBaobQVp"
transaction_id: 5587854
transaction_status: "SUCCESS"
transaction_error_code: 0
transaction_timestamp: 1647781034
card_token: null
bill_token: "62065b8d-589c-4f00-8f1f-3fcf5d12f1cb"
payment_method_type: "CC"
amount: 15.00
currency_iso: "EUR"
order_id: "891544ML"
user_id: "565"
custom:
  custom_user_phone: "+37052141409"
  custom_device_fingerprint: "myAwesomeDeviceFingerprint"
  custom_merchant_affiliate_id: "myAwesomeAffiliate_id-789369"
  custom_merchant_product_name: "myAwesomeProductName"
  custom_merchant_domain_name: "myAwesomeDomain"
PARAMETER DESCRIPTION
is_test Indicates if a test payment method is used.
api_key Your personal API key from genome portal.
signature Signature parameter to ensure that callback is provided by Genome. The generation is explained below.
session_id The unique session ID.
transaction_id The unique transaction ID.
transaction_status The transaction status.
transaction_error_code The transaction error code.
transaction_timestamp The transaction UNIX timestamp in seconds.
card_token Card token.
bill_token Bill token.
payment_method_type Type of payment method, "CC" for credit card.
amount The transaction amount.
currency_iso The transaction currency in ISO 4217 format.
order_id The transaction order ID.
user_id The transaction user ID.
custom Any custom parameters provided by the merchant.

Callbacks are available in the following formats: JSON, XML, YAML. The configuration of the callback format is available while creating the hosted payment page.

Callback signature calculation

Each callback has signature parameter to ensure that callback is provided by Genome. It is generated using the following rule:

PARAMETER DESCRIPTION
api_secret Your personal secret key, which you created within the Genome portal.
session_id The unique session ID.
order_id The transaction order ID.
transaction_id The unique transaction ID.
amount The transaction amount.
currency_iso The transaction currency in ISO 4217 format.

The SHA256 hash function is applied to the string using | separator:

Code example:

  STRING: myAwesomeSecret|b1ca6fef32a1|order_100500|6033718|100.04|USD
  SHA256: b743b9408dea1ec1c5385f79981cad6a4db4dc8e8318abf97c8508df9b4bd9bd

  STRING: myAwesomeSecret|0e90952e5244||84309221|100.04|EUR
  SHA256: d3d62e2552c5693dfb204600e1fe13ffc9a571a8558bca610fdae2d35ea51c62
api_secret session_id order_id transaction_id amount currency_iso

Payout API

Overview

Genome provides merchants functionality which allows to make payouts to their customers.

Web Service URL
Live Genome Payout API Service https://api.genome.eu/api/pf/payout

Payout request formats

Payout on credit card

Sample code of the Payout by Credit card request in application/json format:

  {
    "api_version": 1,
    "method": "init",
    "merchant_account": "Account_MP_TRX",
    "merchant_password": "password123",
    "transaction_unique_id": "payout_via_cc",
    "amount": 10,
    "currency": "USD",
    "callback_url": "https://merchant.com/callback",
    "user_id": "user123",
    "user_ip": "127.0.0.1",
    "user_email": "john.doe@example.com",
    "card": {
      "card_cvv": "029",
      "card_number": "4012000300001003",
      "card_holder": "John Doe",
      "card_exp_year": "2022",
      "card_exp_month": "07"
    }
  }

Parameters of the payout request on credit card via full credit card data:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes float
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant API login
merchant_password yes string (6-32) Merchant API password
method yes string
Possible value: init		 Method for the payout request
transaction_unique_id yes string (11-45) Transaction unique identifier in Merchant system.
mid_reference optional string (16) MID reference in Genome system
amount yes float (0 - 9999999.9999) Payout transaction amount
currency yes string (3)
ISO 4217 (alfa-3)		 Payout transaction currency
callback_url yes Not Empty String
https required		 Once the order has been processed merchant will receive a final response (callback) regarding the transaction status to this URL
user_id yes string (1-32) User Id on merchant's side
user_email yes string (6-255) Customer's email address
user_ip optional string (IPv4, IPv6) Customer's IP address. Not all acquirers support IPv6 format
user_first_name optional string (1-32) The first name of the customer
user_last_name optional string (1-32) The last name of the customer
user_address optional string (2-64) Customer's address
user_city optional string (2-32) Customer's city
user_state optional string (1-32) Customer's state
user_country optional string (2-3)
ISO 3166-1 alpha-3		 Customer's country
user_zip optional string (2-10) Customer's zip
user_phone optional string (7-15) Customer's phone number. For testmode the value should be passed with + symbol
card[card_number] yes string (13-19 digits)
Luhn algorithm		 Number of the card
card[card_exp_month] optional string (2 digits) Card expiration month. Month number from '01' to '12'
card[card_exp_year] optional string (4 digits) Card expiration year
card[card_cvv] optional string (3-4 digits) Card Verification Value
card[card_holder] optional string (2-32) Cardholder name

Sample code of the Payout by Credit card response in application/json format:

  {
    "sessionid": "5118fcfc-2d9c-492c-9f7c-21470c",
    "timestamp": 1531741112,
    "status": "pending",
    "code": 0,
    "message": "Request processed successfully"
  }

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
session_id string (36) Unique session Id of the request
timestamp integer
unix timestamp		 Payout API response time
status string
Possible values: success, decline, error		 Status of the request to Payout API
code integer (1-4) Response code of the request
message string (6-255) Response message of the request

Notice: in case of successful request merchant will receive status=pending and code=0 in response. Be advised that the final status of the payout request merchant will receive in callback data, more details regarding callback data is provided below.

Notice: Response is not a finished status of the transaction. Finished status will be sent in callback request.

Payout via Token

Sample code of the Payout by Token request in application/json format:

  {
    "api_version": 1,
    "method": "init",
    "merchant_account": "Account_MP_TRX",
    "merchant_password": "password123",
    "transaction_unique_id": "payout_via_token",
    "amount": 10,
    "currency": "USD",
    "callback_url": "https://merchant.com/callback",
    "user_id": "user123",
    "user_ip": "127.0.0.1",
    "user_email": "john.doe@example.com",
    "card": {
      "token": "5aaaa194-1d68-4ef8-a72f-009184ee03a6",
      "card_holder": "John Doe"
    }
  }

Merchant can use Token value instead of full credit card data. Token is hashed data of the credit card. Token value contains of credit card number, expiry date and card holder name.

Parameters of the payout request on credit card via Token:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes float
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant API login
merchant_password yes string (6-32) Merchant API password
method yes string
Possible value: init		 Method for the payout request
transaction_unique_id yes string (11-45) Transaction unique identifier in Merchant system.
mid_reference optional string (16) MID reference in Genome system
amount yes float (0 - 9999999.9999) Payout transaction amount
currency yes string (3)
ISO 4217 (alfa-3)		 Payout transaction currency
callback_url yes Not Empty String
https required		 Once the order has been processed merchant will receive a final response (callback) regarding the transaction status to this URL
user_id yes string (1-32) User Id on merchant's side
user_email yes string (6-255) Customer's email address
user_ip optional string (IPv4, IPv6) Customer's IP address. Not all acquirers support IPv6 format
user_first_name optional string (1-32) The first name of the customer
user_last_name optional string (1-32) The last name of the customer
user_address optional string (2-64) Customer's address
user_city optional string (2-32) Customer's city
user_state optional string (1-32) Customer's state
user_country optional string (2-3)
ISO 3166-1 alpha-3		 Customer's country
user_zip optional string (2-10) Customer's zip
user_phone optional string (7-15) Customer's phone number. For testmode the value should be passed with + symbol
card[card_token] yes string (36) Hashed value of card number, expiry date and cardholder name
card[card_holder] optional string (2-32) Cardholder name

Sample code of the Payout by Token response in application/json format:

  {
    "sessionid": "5118fcfc-2d9c-492c-9f7c-21470a",
    "timestamp": 1531741112,
    "status": "pending",
    "code": 0,
    "message": "Request processed successfully"
  }

Response parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
session_id string (36) Unique session Id of the request
timestamp integer
unix timestamp		 Payout API response time
status string
Possible values: success, decline, error		 Status of the request to Payout API
code integer (1-4) Response code of the request
message string (6-255) Response message of the request

Notice: in case of successful request merchant will receive status=pending and code=0 in response. Be advised that the final status of the payout request merchant will receive in callback data, more details regarding callback data is provided below.

Notice: Response is not a finished status of the transaction. Finished status will be sent in callback request.

Payout callback

Example of callback request to merchant in "application/x-www-form-urlencoded" format:


    token=5aaaa194-1d68-4ef8-a72f-009184ee03a6
    &reference=PTFF00000000396580CF
    &transaction_unique_id=payout_0716100000
    &status=success
    &code=0
    &message=Transaction processed successfully
    &checkSum=4804928393234a6cd05f177569147091d7138da25fc61d9ee5add357017239a6

Callback request parameters:

PARAMETER NAME FORMAT and RULE DESCRIPTION
token string (36) Hashed value of card number, expiry date and cardholder name
reference string (20) Reference of the transaction in Genome system
transaction_unique_id string (11-45) Unique transaction Id
status string
Possible values: success, decline, error		 Status of the transaction
code integer (1-4) Response code regarding the transaction result
message string (6-255) Response message regarding the transaction result
checkSum string (64) Signature for callback parameters

Genome sends callback data to merchant in application/x-www-form-urlencoded format. Callback is received to a merchant when in response Genome got the code - 200 (it's required), and body text - OK (it's optional). In other cases, callback is not received to merchant and Genome will try periodically to re-send callback data. The number of attempts are limited.

checkSum calculation

checkSum calculation allows to compare value of the checkSum in callback request with own calculation.

PHP algorithm below shows the calculation logic of “checkSum”:


    <?php

        // Example of the callback request to merchant, application/x-www-form-urlencoded format.
        $callbackData = 'token=5aaaa194-1d68-4ef8-a72f-009184ee03a6&reference=PTFF00000000396580CF&transaction_unique_id=payout_0716100000&status=success&code=0&message=Transaction processed successfully&checkSum=4804928393234a6cd05f177569147091d7138da25fc61d9ee5add357017239a6';

        // Example of the sorted parameters. Also, private key, provided by Genome is added in the end of the line.
        $sortedData = 'code=0|message=Transaction processed successfully|reference=PTFF00000000396580CF|status=success|token=5aaaa194-1d68-4ef8-a72f-009184ee03a6|transaction_unique_id=payout_0716100000|your_private_key';

        // Getting the result of checkSum calculation
        $countedCheckSum = hash('sha256', $sortedData);

    ?>

If you need to calculate and compare the value checkSum callback, use the algorithm described below:

Make notice, that all callback values take a part in calculation of the checkSum parameter.

Make notice, that a value of the your_privat_signature is your current merchant account password

If fully translate callback shown in the example into the line we get:

Transaction statuses

Payout transaction statuses:

Status Description
NEW transaction payout created
SUCCESS transaction processed successfully
ERROR transaction error
DECLINED transaction declined
VOIDED transaction is voided
PROCESSING transaction processing
PENDING PROCESSING transaction in queue
PROCESSING POSTBACK processing postback

Payout response codes

List of the response codes for payout transactions:

Module Code Message (can be extended depending on case)
Payout 3300 GENERAL DECLINE
3310 VALIDATION DECLINE
3311 INVALID MID REFERENCE
3330 UNREGISTERED CARD

Query on demand API

With the help of Genome query on demand API you will be able to get the historical data for each transaction processed by you.

Access to Genome Qod API

Genome live and test query on demand API could be reached by the following URL:

Web Service URL
Live QOD Service https://api.genome.eu/api/pf/qod

QoD Workflow

The Merchant requests transactions data for own account from QOD Service API using the methods defined below. QOD Service API returns reports for each request according for the requested type and transaction report type.

QoD Request formats

Request parameters are general for all request types

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes float (1)
Possible value: 1		 API version
merchant_account yes string (6-32) Merchant API login
merchant_password yes string (6-32) Merchant API password
time_from yes string (unix timestamp) Processing transaction time FROM
time_to yes string (unix timestamp) Processing transaction time TO
qod_type yes string
Possible values: transactions, chargebacks		 Transaction types are used for the request: transactions, chargebacks
order no1 string
Possible values: acs, desc		 Ordering ASC (by default)/DESC
page no2 string (1-12) Fetching page number. If response contains transactions quantity more than limit, paged fetching is possible. A page contains the Limited number of records (Limit).
limit no3 string (1-1000) Quantity of the fetched transactions. 1000 by default. Can’t be greater than 1000

Note 1: If Order is not defined, uses ASC ordering
Note 2: If Page is not defined, only transactions for 1st page should be fetched according to the set Limit
Note 3: If Limit is not defined, 1000 transactions should be fetched.

Sample code of the Transaction request in "application/json" format:

  {
    "api_version": 1,
    "merchant_account": "Account_MP_TRX",
    "merchant_password": "password123",
    "time_from": "1508001644",
    "time_to": "1808001645",
    "qod_type": "transactions",
    "order": "asc",
    "page": "1",
    "limit": "50"
  }

QoD Response formats

The information should be requested page by page, divided on 1000 records on page. It is possible to request any page by number.

Transactions

Sample code of the Transaction response in "application/json" format:

  {
    "api_version": 1,
    "timestamp": 1545117788.019275,
    "session_id": "FbIBcVN/Ht5LorIpqfsm",
    "merchant_account": "Account_MP_TRX",
    "transactions": [
      {
        "transaction_type": "AUTH",
        "status": "SUCCESS",
        "mode": "CC",
        "reference": "ATFF00000000395376F6",
        "base_reference": null,
        "amount": 10,
        "currency": "GBP",
        "merchant": {
          "merchant_account": "Account_MP_TRX",
          "descriptor_merchant": "",
          "descriptor_phone": "",
          "merchant_domain_name": "",
          "merchant_product_name": "",
          "merchant_affiliate_id": "",
          "merchant_user_id": ""
        },
        "user": {
          "first_name": "John",
          "last_name": "Doe",
          "country": "GBR",
          "state": "",
          "city": "London",
          "address": "123 Streetname",
          "zip": "11111",
          "user_ip": "127.0.0.1",
          "user_email": "johndoe@test.com",
          "user_phone": "+123456789012"
        },
        "card": {
          "card_holder": "John Doe",
          "brand": "VISA",
          "bank": "TEST BANK",
          "level": "CLASSIC",
          "type": "DEBIT",
          "bin": "400002",
          "last": "1234",
          "exp_month": "06",
          "exp_year": "2023"
        },
        "bank": {
          "id": 1,
          "authcode": "111737",
          "time": 1532542316.3496
        },
        "time": 1520447215.4163,
        "token": "54817d79-8b5c-4c6f-a266-7f2264ed02ad",
        "transaction_unique_id": "accept.1420447212.1505680771",
        "pares": "",
        "code": 0,
        "message": "SUCCESS"
      }
    ],
    "status": "success",
    "code": 0,
    "message": "Transaction processed successfully"
  }

Purpose: Use transactions request qod_type allows to get all of transactions processed on the merchant account.

Response parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes float (1)
Possible value: 1		 API version
timestamp yes integer
unix timestamp		 Query on Demand API response time
session_id yes string (36) Unique session Id of the request
merchant_account yes string (6-32) Merchant API login
transactions yes array Contains of transactions data
transaction_type yes string
Possible values: SALE, AUTH, AUTH3D, SALE3D, SETTLE, REFUND, VOID		 Type of the transaction
status yes string
Possible values: SUCCESS, DECLINED, ERROR, MALFORMED, FRAUDED, CHARGEDBACK, REFUNDED, VOIDED, PARTIAL-REFUNDED, WRONGREF		 Status of the transaction
mode yes string
Possible values: CC, TOKEN, REF, CASCADE		 Transaction mode.
  • CC - by credit card.
  • TOKEN - by token.
  • REF - by reference.
  • CASCADE - by cascade mode.
reference yes string (20) Reference of the transaction in Genome system.
base_reference yes null or string (20) Base reference of the transaction in Genome system if exists.
amount yes float (0 - 9999999.9999) Transaction amount
currency yes string (3)
ISO 4217 (alfa-3)		 Transaction currency
merchant yes array or null Contains of merchant data
merchant_account yes string (6-32) Merchant API login
descriptor_merchant yes null or string (0-255) Merchant descriptor
descriptor_phone yes null or string (0-255) Merchant descriptor phone
merchant_domain_name yes null or string (0-255) Merchant website name
merchant_product_name yes null or string (0-255) Merchant product name
merchant_affiliate_id yes null or string (0-255) Merchant affiliate identifier
merchant_user_id yes null or string (0-32) Unique user Id in Merchant system
end of the merchant array -//- -//- End of the merchant array
user yes array or null Contains of user data
first_name yes string (1-32) The first name of the customer
last_name yes string (1-32) The last name of the customer
country yes string (3)
ISO 3166-1 alpha-3		 Customer's country
state yes null or string (1-32) Customer's state
city yes null or string (2-32) Customer's city
address yes null or string (2-64) Customer's address
zip yes null or string (2-10) Customer's zip
user_ip yes string (IPv4, IPv6) Customer's IP address
user_email yes string (6-255) Customer's email
user_phone yes null or string (7-15) Customer's phone number
end of the user array -//- -//- End of the user array
card yes array or null Contains of custmer's card data
card_holder yes string (2-32) Card holder name
brand yes string (0-255) Card brand - VISA, MASTERCARD, AMEX, JCB etc
bank yes string (0-255) Issuer bank
level yes string (0-255) Level of the card - ELECTRON, CLASSIC etc
type yes string (0-255) Type of the card - CREDIT, DEBIT etc
bin yes string (6) The first 6 digits of the card
last yes string (4) The last 4 digits of the card
exp_month yes string (2) Card expiration month
exp_year yes string (4) Card expiration year
end of the card array -//- -//- End of the card array
bank yes array or null Contains of acquirer data
id yes integer (0-20) Bank identifier code
authcode yes string (0-45) Bank authorization code
time yes float or null Bank transaction time
end of the bank array -//- -//- End of the bank array
time yes float or null Transaction time in Genome system, UTC timezone
token yes string (36) Hashed value of card number, expiry date and cardholder name.
transaction_unique_id yes string (11-45) Transaction unique identifier in Merchant system.
pares yes string (0-65535) The hashed value of the result of 3D Secure authorization
code yes null or integer(1-4) Transaction response code, check the response codes table below
message yes null or string (6-255) Transaction response message, check the response codes table below
end of transactions array -//- -//- End of the transactions array
status yes string
Possible values: success, error		 Status of the request to QoD API
code yes integer (1-4) Response code of the request to QoD API
message yes string (6-255) Response message of the request to QoD API

Chargebacks

Sample code of the Chargebacks response in "application/json" format:

  {
    "api_version": 1,
    "timestamp": 1545117788.019275,
    "session_id": "FbIBcVN/Ht5LorIpqfsm",
    "merchant_account": "Account_MP_TRX",
    "chargebacks": [
      {
        "transaction": {
          "transaction_type": "SETTLE",
          "status": "CHARGEDBACK",
          "mode": "REF",
          "reference": "STFF0000000039546C12",
          "base_reference": "ATFF0000000039546BBF",
          "amount": 10,
          "currency": "GBP",
          "merchant": {
            "merchant_account": "Account_MP_TRX",
            "descriptor_merchant": "",
            "descriptor_phone": "",
            "merchant_domain_name": "",
            "merchant_product_name": "",
            "merchant_affiliate_id": "",
            "merchant_user_id": ""
          },
          "user": {
            "first_name": "John",
            "last_name": "Doe",
            "country": "GBR",
            "state": "",
            "city": "London",
            "address": "123 Streetname",
            "zip": "11111",
            "user_ip": "127.0.0.1",
            "user_email": "johndoe@test.com",
            "user_phone": "+123456789012"
          },
          "card": {
            "card_holder": "John Doe",
            "brand": "VISA",
            "bank": "TEST BANK",
            "level": "CLASSIC",
            "type": "DEBIT",
            "bin": "400002",
            "last": "1234",
            "exp_month": "06",
            "exp_year": "2023"
          },
          "bank": {
            "id": 1,
            "authcode": "111575",
            "time": null
          },
          "time": 1621938805.751,
          "token": "",
          "transaction_unique_id": "transaction_52525251",
          "pares": "",
          "code": 0,
          "message": "SUCCESS"
        },
        "chargeback": {
          "status": "OPENED",
          "type": "CHARGEBACK_REVERSAL",
          "reason": "3102",
          "description": "Lost/Stolen card",
          "transaction_type": "CHARGEBACK",
          "transaction_status": "SUCCESS",
          "mode": "REF",
          "reference": "CBFF000000003958A4B1",
          "base_reference": "STFF0000000039546C12",
          "amount": 10,
          "currency": "GBP",
          "transaction_unique_id": "transaction_52525251",
          "arn": "",
          "case_id": "",
          "bank": {
            "id": 1,
            "authcode": "",
            "time": 1628576548.6336,
            "update_time": 1628576548.6336
          },
        "time": 1728576550.499
        }
      }
    ],
    "status": "success",
    "code": 0,
    "message": "Transaction processed successfully"
  }

Purpose: Use сhargebacks request qod_type allows to get all chargebacked transactions on the merchant account.

Response parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes float (1)
Possible value: 1		 API version
timestamp yes integer
unix timestamp		 Query on Demand API response time
session_id yes string (36) Unique session Id of the request
merchant_account yes string (6-32) Merchant API login
chargebacks yes array Contains of chargebacks data
transaction yes array Contains of transaction data
transaction_type yes string
Possible values: SALE, SALE3D, SETTLE		 Type of the transaction
status yes string
Possible value: CHARGEDBACK		 Status of the transaction
mode yes string
Possible values: CC, TOKEN, REF, CASCADE		 Transaction mode.
  • CC - by credit card.
  • TOKEN - by token.
  • REF - by reference.
  • CASCADE - by cascade mode.
reference yes string (20) Reference of the transaction in Genome system.
base_reference yes null or string (20) Base reference of the transaction in Genome system if exists.
amount yes float (0 - 9999999.9999) Transaction amount
currency yes string (3)
ISO 4217 (alfa-3)		 Transaction currency
merchant yes array or null Contains of merchant data
merchant_account yes string (6-32) Merchant API login
descriptor_merchant yes null or string (0-255) Merchant descriptor
descriptor_phone yes null or string (0-255) Merchant descriptor phone
merchant_domain_name yes null or string (0-255) Merchant website name
merchant_product_name yes null or string (0-255) Merchant product name
merchant_affiliate_id yes null or string (0-255) Merchant affiliate identifier
merchant_user_id yes null or string (0-32) Unique user Id in Merchant system
end of the merchant array -//- -//- End of the merchant array
user yes array or null Contains of user data
first_name yes string (1-32) The first name of the customer
last_name yes string (1-32) The last name of the customer
country yes string (3)
ISO 3166-1 alpha-3		 Customer's country
state yes null or string (1-32) Customer's state
city yes null or string (2-32) Customer's city
address yes null or string (2-64) Customer's address
zip yes null or string (2-10) Customer's zip
user_ip yes string (IPv4, IPv6) Customer's IP address
user_email yes string (6-255) Customer's email
user_phone yes null or string (7-15) Customer's phone number
end of the user array -//- -//- End of the user array
card yes array or null Contains of custmer's card data
card_holder yes string (2-32) Card holder name
brand yes string (0-255) Card brand - VISA, MASTERCARD, AMEX, JCB etc
bank yes string (0-255) Issuer bank
level yes string (0-255) Level of the card - ELECTRON, CLASSIC etc
type yes string (0-255) Type of the card - CREDIT, DEBIT etc
bin yes string (6) The first 6 digits of the card
last yes string (4) The last 4 digits of the card
exp_month yes string (2) Card expiration month
exp_year yes string (4) Card expiration year
end of the card array -//- -//- End of the card array
bank yes array or null Contains of acquirer data
id yes integer (0-20) Bank identifier code
authcode yes string (0-45) Bank authorization code
time yes float or null Bank transaction time
end of the bank array -//- -//- End of the bank array
time yes float or null Transaction time in Genome system, UTC timezone
token yes string (36) Hashed value of card number, expiry date and cardholder name.
transaction_unique_id yes string (11-45) Transaction unique identifier in Merchant system.
pares yes string ( 0-65535) The hashed value of the result of 3D Secure authorization
code yes null or integer(1-4) Transaction response code, check the response codes table below
message yes null or string (6-255) Transaction response message, check the response codes table below
end of transaction array -//- -//- End of the transaction array
chargeback yes array Contains of chargeback data
status yes string Possible values: OPENED, REVERSED, CLOSED, REPRESENTED Chargeback status
type yes string Possible values: FIRST_CHARGEBACK, SECOND_THIRD_CHARGEBACK, CHARGEBACK_REVERSAL, LOST_REPRESENTMENT, REPRESENTMENT, RETRIEVAL_REQUEST Chargeback type
reason yes string (0-255) Chargeback reason
description yes string (0-255) Chargeback description
transaction_type yes string
Possible value: CHARGEBACK		 Chargeback transaction type
transaction_status yes string
Possible values: SUCCESS, ERROR		 Chargeback transaction status
mode yes string
Possible value: REF		 Chargeback transaction mode
reference yes string (20) Reference of the chargebacked transaction in Genome system
base_reference yes string (20) Base reference of the chargebacked transaction in Genome system
amount yes float (0 - 9999999.9999) Amount of the chargebacked transaction
currency yes string (3)
ISO 4217 (alfa-3)		 Currency of the chargebacked transaction
transaction_unique_id yes string (11-45) Unique chargebacked transaction identifier in Merchant system.
arn yes null or string (0-255) Actual Reference number
case_id yes null or string (0-255) Identifier from acquirer side.
bank yes array or null Contains of acquirer data
id yes integer (0- 20) Bank identifier code
authcode yes string (0-45) Bank authorization code
time yes float or null Chargeback time by bank
update_time yes float or null Transaction status updated time by bank
end of the bank array -//- -//- End of the bank array
time yes float or null Time of updating a transaction status at Genome system
end of the chargeback array -//- -//- End of the chargeback array
end of the chargebacks array -//- -//- End of the chargebacks array
status yes string
Possible values: success, error		 Status of the request to QoD API
code yes integer (1-4) Response code of the request to QoD API
message yes string (6-255) Response message of the request to QoD API

Request validation specified (not API) response codes

Code Message (can be extended depending on case)
400 Cannot read incoming request data

Empty response

Purpose: The following fieldset should be transmitted in case of empty response data.

Response parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes float (1)
Possible value: 1		 API versionAPI version
merchant_account yes string (6-32) Merchant API login
timestamp yes integer
unix timestamp		 Query on Demand API response time
transactions \ chargebacks yes array or null QOD type
status yes string
Possible values: success, error		 Status of the request to QoD API
code yes integer (1-4) Response code of the request to QoD API
message yes string (6-255) Response message of the request to QoD API

Erroneous response

Example of response in JSON:

  {
    "api_version": 1,
    "transactions": [],
    "merchant_account": "Account_MP_TRX",
    "timestamp": 1532216783.6329,
    "status": "error",
    "code": 5008,
    "message": "Time from cannot be greater than Time to"
  }

Purpose: The following fieldset should be transmitted in case of erroneous request/response data.

Response parameters:

PARAMETER NAME REQUIRED FORMAT and RULE DESCRIPTION
api_version yes float (1)
Possible value: 1		 API versionAPI version
merchant_account yes string (6-32) Merchant API login
timestamp yes integer
unix timestamp		 Query on Demand API response time
transactions \ chargebacks yes array or null QOD type
status yes string
Possible value: error		 Status of the request to QoD API
code yes integer (1-4) Response code of the request to QoD API
message yes string (6-255) Response message of the request to QoD API

Response statuses

CODE DESCRIPTION
success Succesful QOD response
error Unsuccesful QOD response

QoD API specified response codes

CODE MESSAGE DESCRIPTION (can be extended depending on case)
5000 QOD GENERAL ERROR QoD general error
5001 QOD UNSUPPORTED API VERSION Unsupported QoD API version
5002 INVALID TIME ORDER Time from cannot be more than time to

Response codes

List of response codes

Purpose: The following codes will be transmited in each response. Response Description contains extended information to describe the result of processed transaction.

CODE MESSAGE (CAN BE EXTENDED DEPENDING ON CASE)
0 Transaction processed successfully
1 General internal service error
2 Internal DB error
3 General service error
4 Access denied
10 General internal service communication error
11 Internal timeout
12 Internal SSL error
1000 Merchant gate error
1001 Request format error
1002 [field] not present in request
1003 Internal communication error
1004 Invalid [field] in request message
1005 Unsupported API version
1006 [field] should not be present in request
2000 General MMS error
2001 Incorrect value in merchant account or pass field
2002 Country is not available
2003 Merchant account exists but not active
2004 Transaction is not allowed to account
2005 MID is not active
2006 There is no currency configured for account
2007 Amount is below or above amount restrictions
2008 Access from this IP-address is not available
2009 Merchant is not activated
2010 Gate is not active
2011 Entity already exists
2012 Entity not found
2013 Bad API credentials
3000 General processing error
3001 Transaction ID/Order ID is already used
3002 Token not found or invalid
3003 Reference not found or invalid
3004 It is not possible to void the the provided reference
3005 It is not possible to refund the provided reference
3006 Transaction is chargebacked
3007 Illegal interval between AUTH and SETTLE/VOID, between AUTH 3D and SETTLE/SALE
3008 Transaction was already voided
3009 Transaction was already refunded
3010 Transaction was already settled
3011 MID doesn't support the card type
3012 Account doesn't support 3D secure
3013 Account support only 3D secure transaction
3014 There was no transaction found on your Check request
3015 Bank MID doesn't support the currency
3016 Amount in settle transaction is incorrect
3017 Bank MID access credentials are incorrect
3018 Bank refused the connection
3019 Request cannot be validated
3020 Chargeback is invalid
3021 Transaction is blocked by routing
3022 The amount is incorrect
3023 Transaction is aborted by the customer
3024 Transaction is expired
3025 Transaction is completed
3027 Pending MSISDN found
3100 Transaction declined by bank network
3101 Insufficient funds
3102 Card lost or stolen
3103 3d secure authentication failed
3104 Invalid CVV
3105 Card expired due to expiry date or expiry date is not correct
3106 Bank cannot process selected amount
3107 Invalid card number
3108 It is not possible to issue refund due to bank limit
3109 Timeout between PSP and bank
3110 Not all required data was provided to the specific bank
3111 Access error to a bank acquirer
3112 Card type is not supported by MID
3113 Transaction type is not supported by MID
3114 Currency is not supported by MID
3115 Refund not possible by bank
3116 Country is not supported by MID
3117 Malformed bank response
3118 Connection error between PSP and bank
3119 Referal or restricted card
3120 Risk Bank Decline
3121 Invalid acquirer token
3122 Invalid acquirer reference
3123 Card 3D secure is not enabled
3124 Unknown acquirer processing status
3125 Acquirer internal error
3126 Withdrawal frequency limit exceeded
3127 Bank negative list
3128 Fraud bank decline
3129 Authorization declined
3130 Revocation of authorization order
3131 Repeats not allowed by operator
3132 Recurring is stopped by the customer
3200 Declined by anti-fraud system
3201 Sent for manual review by anti-fraud system
3202 Volume limit exceeded
3203 Refund limit exceeded
3220 Declined by anti-fraud trust lists
3221 Sent for manual review by anti-fraud trust lists
3300 General payout error
3310 Payout validation error
3311 Invalid mid reference
3330 Unregistered card
4000 General reconciliation error
4001 Reconciliation data is not ready
4002 Reconciliation total amount doesn't match
4003 Reconciliation total count doesn't match
4004 General FRS error
4005 Balance is not available
4006 Currency is not available
4007 Exceeded amount
5000 General QoD error
5001 Unsupported QoD API version
5002 Invalid [time] fields order
6000 General internal auth failure
6001 Wrong credentials
6002 Access denied
6003 The user already exists
6004 The user is not found
6005 The role is not found
6006 The permission is not found
6007 The token is expired
6008 The token is not found
6009 The user is temporary blocked
6010 The password is expired
6011 The password is invalid
6012 The password is previously used
6013 Recovery key have been used
6014 Request totp from user
7000 Internal payment gate error
7101 Internal payment gate sender error
7102 External communication error
7103 External communication timeout
8000 General internal stats failure
8001 Date range is too long for selected aggregation interval

Behavior on response codes

RC TRANSACTION RESULT ACTION
0 SUCCESS
2 unknown CHECK transaction status
3 unknown CHECK transaction status
10 unknown CHECK transaction status
11 unknown CHECK transaction status
12 unknown CHECK transaction status
1003 unknown CHECK transaction status
6000 unknown CHECK transaction status
OTHER RC DECLINE

PSD2 API

Open Banking with PSD2

The revised Payment Services Directive (PSD2) requires banks to allow third party providers (TPPs) to access account and make payments on their customer’s behalf and with their consent. This regulation ensures that banks put into place the necessary systems to securely and reliably share their services and data with registered TPP. APIs are already widely used across the internet to share information and provide secure access to accounts and payment services.

Genome PSD2 API

Genome open API can be used for both account information (AISP) and payment services (PISP). Since our priority is to secure customer’s data and ensuring a smooth customer experience, as well as adhering to market standards, our PSD2 services are based on OAuth2.0 method. Our PSD2 API are free to use for all registered AISPs and PISPs. If you are a registered TPP and wish to use our API, please contact us at psd2@genome.eu

This API can be used to access the accounts IBAN of Genome customers. This API definition is based on the Implementation Guidelines of the Berlin Group PSD2 API. It is not an replacement in any sense. The main specification is (at the moment) always the Implementation Guidelines of the Berlin Group PSD2 API.

Authentication

Genome API implements OAuth 2.0 to allow users to log in to applications without exposing their credentials. The process involves several steps:

  1. Acquire an access token, and optionally a refresh token
  2. Use the access token to make authenticated requests

Strong Customer Authentication
We don’t grant any permissions to the access token until the owner of the account that your client wants to access has approved access. Your user will receive a sms or email notification after authenticating with their phone or email.

Acquire an access token

Acquiring an access token is a three-step process:

  1. Redirect the user to Genome to authorise your app
  2. Exchange the authorization code for an access token.

This access token doesn’t have any permissions until your user has approved access to their data.

Base URLs
We’ve included the Base URL for Production environment below.
Production https://my.genome.eu/oauth2

Redirect the user to Genome

Endpoint

  /oauth2/authorize?client_id={client_id}&response_type=code&redirect_uri={uri}&state={random_string}

Response Body (Example)

  Response example
    1. User already authenticated response = 302 redirect to OAUTH2 approval page
    2. Unauthorized HTTP 302 redirect to login page

Send the user to Genome in a web browser, where they will log in and grant access to their account.

Strong Customer Authentication

In addition to authenticating with email or phone, the user will receive a OTP code to email or phone to confirm authentication with second factor.

Request Method
GET

PARAMETER NAME REQUIRED FORMAT AND RULES To DESCRIPTION
client_id Yes String Path Your client ID.
redirect_uri Yes String Path A URI to which users will be redirected after authorising your app.
response_type Yes String Path Must be set to code.
state Yes String Path An unguessable random string used to protect against cross-site request forgery attacks.

Exchange the authorization code

Endpoint

  /oauth2/token

Request Body (Example)

  grant_type=authorization_code&code={code}&redirect_uri={uri}&client_id={client_id}

Response Body (Example)

  {
      "access_token": "MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
      "token_type": "bearer",
      "expires_in": 3600,
      "scope": "{scope}"
  }

When you receive an authorization code, exchange it for an access token. The resulting access token is tied to both your client and an individual Genome user, and is valid for 30 minutes.

Request Method
POST

PARAMETER NAME REQUIRED FORMAT AND RULES To DESCRIPTION
Content-Type Yes String Header application/x-www-form-urlencoded
Authorization Yes String Header Basic base64(client_id:client_secret)
grant_type Yes String Body This must be set to authorization_code.
client_id Yes String Body The client ID you received from Genome.
redirect_uri Yes String Body The URL in your app where users were sent after authorisation.
code Yes String Body The authorization code you received when the user was redirected back to your app.

Authenticating requests

All requests must be authenticated with an access token supplied in the Authorization header using the Bearer scheme. Your client may only have one active access token at a time, per user. Acquiring a new access token will invalidate any other token you own for that user.

Account Information Services API

The Account Information Services API lets authorised Account Information Service Providers (AISP) access balances, transactions, and more for our customers.

Base URLs
We’ve included the Base URL for Production environment below.
Production https://my.genome.eu/psd2/

Endpoint

  /psd2/v1/consents

Request Body (Example)

  {
    "access": {
      "accounts": [{
        "currency": "EUR",
        "iban": "{{iban_none}}"
      }],
      "balances": [{
        "currency": "EUR",
        "iban": "{{iban_none}}"
      }],
      "transactions": [{
        "currency": "EUR",
        "iban": "{{iban_none}}"
      }]
    },
    "combinedServiceIndicator": false,
    "frequencyPerDay": 400,
    "recurringIndicator": true,
    "validUntil": "2021-12-31"
  }

Response Body (Example)

  {
    "consentStatus": "received",
    "consentId": "7uhkasdtaydfem43",
    "_links": {
      "self": {
        "href": "/psd2/v1/consents/7uhkasdtaydfem43"
      },
      "startAuthorisation": {
        "href": "/psd2/v1/consents/7uhkasdtaydfem43/authorisations"
      },
      "status": {
        "href": "/psd2/v1/consents/7uhkasdtaydfem43/status"
      }
    },
    "psuMessage": "OTP Password required"
  }

Creates an account information consent resource at the ASPSP regarding access to accounts specified in this request.

Request Method
POST

PARAMETER NAME REQUIRED FORMAT AND RULES To DESCRIPTION
Content-Type Yes String Header application/json
Authorization Yes String Header Bearer {oauth2_token}
Tpp-Qwac-Certificate Yes String Header {ttp_uploaded_certificate}
QWAC certificate without line breaks with boundaries
-----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE-----
X-Request-ID Yes String Header ID of the request, unique to the call, as determined by the initiating party.
PSU-IP-Address Yes String Header The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. It shall be contained if and only if this request was actively initiated by the PSU.

Endpoint

  /psd2/v1/consents/{consent_id}/authorisations

Request Body (Example)

  Request body is empty

Response Body (Example)

  {
    "scaStatus": "received",
    "authorisationId": "hc7aascfcncf4dhk",
    "_links": {
      "scaRedirect": {
        "href": "/psd2/ais/hc7aascfcncf4dhk/7uhkasdtaydfem43"
      }
    }
  }

Start the authorisation process for a consent

Request Method
POST

PARAMETER NAME REQUIRED FORMAT AND RULES To DESCRIPTION
Content-Type Yes String Header application/json
Authorization Yes String Header Bearer {oauth2_token}
Tpp-Qwac-Certificate Yes String Header {ttp_uploaded_certificate}
QWAC certificate without line breaks with boundaries
-----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE-----
consentId Yes String Path ID of the corresponding consent object as returned by an Account Information Consent Request.
X-Request-ID Yes String Header ID of the request, unique to the call, as determined by the initiating party.

Endpoint

  /psd2/v1/consents/{consent_id}

Response Body (Example)

  {
    "access": {
      "accounts": [{
        "iban": $ {
          iban
        },
        "currency": "EUR"
      }],
      "balances": [],
      "transactions": [],
      "availableAccounts": "allAccounts"
    },
    "recurringIndicator": true,
    "validUntil": "+53743-10-28",
    "frequencyPerDay": 1,
    "lastActionDate": "+51645-08-30",
    "consentStatus": "received"
  }

Returns the content of an account information consent object. This is returning the data for the TPP especially in cases, where the consent was directly managed between ASPSP and PSU e.g. in a re-direct SCA Approach.

Request Method
GET

PARAMETER NAME REQUIRED FORMAT AND RULES To DESCRIPTION
Content-Type Yes String Header application/json
Authorization Yes String Header Bearer {oauth2_token}
Tpp-Qwac-Certificate Yes String Header {ttp_uploaded_certificate}
QWAC certificate without line breaks with boundaries
-----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE-----
consentId Yes String Path ID of the corresponding consent object as returned by an Account Information Consent Request.
X-Request-ID Yes String Header ID of the request, unique to the call, as determined by the initiating party.

Endpoint

  /psd2/v1/consents/{consent_id}/status

Response Body (Example)

  {
    "consentStatus": "received"
  }

Can check the status of an account information consent resource.

Request Method
GET

PARAMETER NAME REQUIRED FORMAT AND RULES To DESCRIPTION
Content-Type Yes String Header application/json
Authorization Yes String Header Bearer {oauth2_token}
Tpp-Qwac-Certificate Yes String Header {ttp_uploaded_certificate}
QWAC certificate without line breaks with boundaries
-----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE-----
consentId Yes String Path ID of the corresponding consent object as returned by an Account Information Consent Request.
X-Request-ID Yes String Header ID of the request, unique to the call, as determined by the initiating party.

Endpoint

  /psd2/v1/consents/{consent_id}/authorisations/{authorisation_id}

Response Body (Example)

  {
    "scaStatus": "psuAuthenticated"
  }

Creates an account information consent resource at the ASPSP regarding access to accounts specified in this request. Side Effects When this Consent Request is a request where the "recurringIndicator" equals true, and if it exists already a former consent for recurring access on account information for the addressed PSU submitted by this TPP, then the former consent automatically expires as soon as the new consent request is authorised by the PSU.

Request Method
GET

PARAMETER NAME REQUIRED FORMAT AND RULES To DESCRIPTION
Content-Type Yes String Header application/json
Authorization Yes String Header Bearer {oauth2_token}
Tpp-Qwac-Certificate Yes String Header {ttp_uploaded_certificate}
QWAC certificate without line breaks with boundaries
-----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE-----
consentId Yes String Path ID of the corresponding consent object as returned by an Account Information Consent Request.
authorisationId Yes String Path Resource identification of the related SCA.
X-Request-ID Yes String Header ID of the request, unique to the call, as determined by the initiating party.

Endpoint

  /psd2/v1/consents/{consent_id}

Response Body (Example)

  Response body is empty

Delete an account information consent object.

Request Method
DELETE

PARAMETER NAME REQUIRED FORMAT AND RULES To DESCRIPTION
Content-Type Yes String Header application/json
Authorization Yes String Header Bearer {oauth2_token}
Tpp-Qwac-Certificate Yes String Header {ttp_uploaded_certificate}
QWAC certificate without line breaks with boundaries
-----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE-----
consentId Yes String Path ID of the corresponding consent object as returned by an Account Information Consent Request.
authorisationId Yes String Path Resource identification of the related SCA.
X-Request-ID Yes String Header ID of the request, unique to the call, as determined by the initiating party.

Get accounts list

Endpoint

  /psd2/v1/accounts

Response Body (Example)

  {
    "accounts": [{
      "resourceId": "1051011800072884134",
      "iban": "LT561010038693502211",
      "currency": "EUR",
      "cashAccountType": "OTHR",
      "status": "enabled",
      "bic": "MNNELT21XXX",
      "usage": "PRIV",
      "balances": [{
        "balanceAmount": {
          "currency": "EUR",
          "amount": "9.0"
        },
        "balanceType": "authorised",
        "lastChangeDateTime": "2019-09-10T11:22:11.470751Z",
        "referenceDate": "2019-09-10"
      }],
      "_links": {
        "transactions": {
          "href": "psd2/v1/accounts/1051097800072884134/transactions"
        }
      }
    }]
  }

Reads a list of bank accounts, with balances where required. It is assumed that a consent of the PSU to this access is already given and stored on the ASPSP system. The addressed list of accounts depends then on the PSU ID and the stored consent addressed by consentId, respectively the OAuth2 access token.

Request Method
GET

PARAMETER NAME REQUIRED FORMAT AND RULES To DESCRIPTION
Content-Type Yes String Header application/json
Authorization Yes String Header Bearer {oauth2_token}
Tpp-Qwac-Certificate Yes String Header {ttp_uploaded_certificate}
QWAC certificate without line breaks with boundaries
-----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE-----
X-Request-ID Yes String Header ID of the request, unique to the call, as determined by the initiating party.
Consent-ID Yes String Header This then contains the consentId of the related AIS consent, which was performed prior to this payment initiation.

Get account balances list

Endpoint

  /psd2/v1/accounts/{account_id}/balances

Response Body (Example)

  {
      "account": {
          "iban": "LT551010000034206191",
          "currency": "EUR"
      },
      "balances": [{
          "balanceAmount": {
              "currency": "EUR",
              "amount": "10"
          },
          "balanceType": "authorised",
          "lastChangeDateTime": "2019-09-12T14:06:23.596594Z",
          "referenceDate": "2019-09-12"
      }]
  }

Reads account data from a given account addressed by "account-id".

Request Method
GET

PARAMETER NAME REQUIRED FORMAT AND RULES To DESCRIPTION
Content-Type Yes String Header application/json
Authorization Yes String Header Bearer {oauth2_token}
Tpp-Qwac-Certificate Yes String Header {ttp_uploaded_certificate}
QWAC certificate without line breaks with boundaries
-----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE-----
account-id Yes String Path This identification is denoting the addressed account. The account-id is retrieved by using a "Read Account List" call. The account-id is the "id" attribute of the account structure. Its value is constant at least throughout the lifecycle of a given consent.
X-Request-ID Yes String Header ID of the request, unique to the call, as determined by the initiating party.
Consent-ID Yes String Header This then contains the consentId of the related AIS consent, which was performed prior to this payment initiation.

Get account transactions list

Endpoint

  /psd2/v1/accounts/{account_id}/transactions

Response Body (Example)

  {
      "account": {
          "iban": "LT551010000034206191",
          "currency": "EUR"
      },
      "transactions": {
          "pending": [{
              "transactionId": "335313",
              "creditorId": "1041097800072641102",
              "valueDate": "2019-09-12",
              "transactionAmount": {
                  "currency": "EUR",
                  "amount": "1.0"
              },
              "currencyExchange": [],
              "creditorName": "Sender",
              "creditorAccount": {
                  "currency": "EUR"
              },
              "ultimateCreditor": "",
              "debtorName": "Receiver",
              "debtorAccount": {
                  "currency": "EUR"
              },
              "remittanceInformationUnstructured": "Ref. Number WBG-1222",
              "remittanceInformationStructured": ""
          }]
      }
  }

Reads account transactions list from a given account addressed by "account-id".

Request Method
GET

PARAMETER NAME REQUIRED FORMAT AND RULES To DESCRIPTION
Content-Type Yes String Header application/json
Authorization Yes String Header Bearer {oauth2_token}
Tpp-Qwac-Certificate Yes String Header {ttp_uploaded_certificate}
QWAC certificate without line breaks with boundaries
-----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE-----
account-id Yes String Path This identification is denoting the addressed account. The account-id is retrieved by using a "Read Account List" call. The account-id is the "id" attribute of the account structure. Its value is constant at least throughout the lifecycle of a given consent.
dateFrom Yes String Query Conditional: Starting date (inclusive the date dateFrom) of the transaction list, mandated if no delta access is required. For booked transactions, the relevant date is the booking date. For pending transactions, the relevant date is the entry date, which may not be transparent neither in this API nor other channels of the ASPSP.
bookingStatus Yes String Query Permitted codes are
  • "booked",
  • "pending" and
  • "both" "booked" shall be supported by the ASPSP. To support the "pending" and "both" feature is optional for the ASPSP, Error code if not supported in the online banking frontend
Available values : booked, pending, both
X-Request-ID Yes String Header ID of the request, unique to the call, as determined by the initiating party.
Consent-ID Yes String Header This then contains the consentId of the related AIS consent, which was performed prior to this payment initiation.

Read Transaction Details

Endpoint

  /psd2/v1/accounts/{account_id}/transactions/{transaction_id}

Reads transaction details from a given transaction addressed by “resourceId” on a given account addressed by "account-id". This call is only available on transactions as reported in a JSON format.

Request Method
GET

PARAMETER NAME REQUIRED FORMAT AND RULES To DESCRIPTION
Content-Type Yes String Header application/json
Authorization Yes String Header Bearer {oauth2_token}
Tpp-Qwac-Certificate Yes String Header {ttp_uploaded_certificate}
QWAC certificate without line breaks with boundaries
-----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE-----
account-id Yes String Path This identification is denoting the addressed account. The account-id is retrieved by using a "Read Account List" call. The account-id is the "id" attribute of the account structure. Its value is constant at least throughout the lifecycle of a given consent.
transactionId Yes String Path This identification is given by the attribute transactionId of the corresponding entry of a transaction list.
X-Request-ID Yes String Header ID of the request, unique to the call, as determined by the initiating party.
Consent-ID Yes String Header This then contains the consentId of the related AIS consent, which was performed prior to this payment initiation.

Payment Initiation Services API

The Payment Initiation Services API lets authorised Payment Initiation Service Providers (PISP) make single payments from the IBAN accounts of our customers.

Base URLs
We’ve included the Base URL for Production environment below.
Production https://my.genome.eu/psd2/

Payment Initiation

Endpoint

  /psd2/v1/payments/sepa-credit-transfers

Request Body (Example)

  {
    "endToEndIdentification": "WBG-123456789",
    "debtorAccount": {
      "currency": "EUR",
      "iban": "LT651010555095422166"
    },
    "instructedAmount": {
      "currency": "EUR",
      "amount": "1.00"
    },
    "creditorAccount": {
      "currency": "EUR",
      "iban": "LT553100016548456548"
    },
    "creditorAgent": "AAAADEBBXXX",
    "creditorName": "WBG",
    "creditorAddress": {
      "buildingNumber": "56",
      "city": "Nürnberg",
      "country": "DE",
      "postalCode": "90543",
      "street": "WBG Straße"
    },
    "remittanceInformationUnstructured": "Ref. Number WBG-1222"
  }

Response Body (Example)

  {
    "transactionStatus": "RCVD",
    "paymentId": "fs37ex3ddjdfcffz",
    "transactionFeeIndicator": false,
    "challengeData": {
      "otpMaxLength": 6,
      "otpFormat": "characters"
    },
    "_links": {
      "scaStatus": {
        "href": "psd2/v1/payments/sepa-credit-transfers/fs37ex3ddjdfcffz/authorisations/azfj3uck7t84fxce"
      },
      "scaRedirect": {
        "href": "psd2/v1/pis/azfj3uck7t84fxce/fs37ex3ddjdfcffz"
      },
      "self": {
        "href": "psd2/v1/payments/sepa-credit-transfers/fs37ex3ddjdfcffz"
      },
      "status": {
        "href": "psd2/v1/payments/sepa-credit-transfers/fs37ex3ddjdfcffz/status"
      }
    }
  }

Creates a payment initiation request at the ASPSP.

Request Method
POST

PARAMETER NAME REQUIRED FORMAT AND RULES To DESCRIPTION
Content-Type Yes String Header application/json
Authorization Yes String Header Bearer {oauth2_token}
Tpp-Qwac-Certificate Yes String Header {ttp_uploaded_certificate}
QWAC certificate without line breaks with boundaries
-----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE-----
payment-service Yes String Path Payment service: Possible values is: payments
payment-product Yes String Path The addressed payment product endpoint, e.g. for SEPA Credit Transfers (SCT). The ASPSP will publish which of the payment products/endpoints will be supported. The following payment products is supported: sepa-credit-transfers
X-Request-ID Yes String Header ID of the request, unique to the call, as determined by the initiating party.
Consent-ID Yes String Header This data element may be contained, if the payment initiation transaction is part of a session, i.e. combined AIS/PIS service. This then contains the consentId of the related AIS consent, which was performed prior to this payment initiation.
PSU-IP-Address Yes String Header The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. It shall be contained if and only if this request was actively initiated by the PSU.

Get Payment Information

Endpoint

  /psd2/v1/payments/sepa-credit-transfers/{payment_id}

Response Body (Example)

  {
    "endToEndIdentification": "WBG-123456789",
    "debtorAccount": {
      "iban": "LT401010000000007777",
      "currency": "EUR"
    },
    "instructedAmount": {
      "currency": "EUR",
      "amount": "1"
    },
    "creditorAccount": {
      "iban": "LT313570012345678933",
      "currency": "EUR"
    },
    "creditorName": "WBG",
    "creditorAddress": {
      "street": "WBG Straße",
      "buildingNumber": "56",
      "city": "Nürnberg",
      "postalCode": "90543",
      "country": "WBG Straße"
    },
    "transactionStatus": "RCVD"
  }

Returns the content of a payment object

Request Method
GET

PARAMETER NAME REQUIRED FORMAT AND RULES To DESCRIPTION
Content-Type Yes String Header application/json
Authorization Yes String Header Bearer {oauth2_token}
Tpp-Qwac-Certificate Yes String Header {ttp_uploaded_certificate}
QWAC certificate without line breaks with boundaries
-----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE-----
payment-service Yes String Path Payment service: Possible values is: payments
payment-product Yes String Path The addressed payment product endpoint, e.g. for SEPA Credit Transfers (SCT). The ASPSP will publish which of the payment products/endpoints will be supported. The following payment products is supported: sepa-credit-transfers
paymentId Yes String Path Resource identification of the generated payment initiation resource.
X-Request-ID Yes String Header ID of the request, unique to the call, as determined by the initiating party.

Read the SCA Status of the payment authorisation

Endpoint

  /psd2/v1/payments/sepa-credit-transfers/{payment_id}/authorisations/{authorisation_id}

Response Body (Example)

  {
    "scaStatus": "started"
  }

This method returns the SCA status of a payment initiation's authorisation sub-resource.

Request Method
GET

PARAMETER NAME REQUIRED FORMAT AND RULES To DESCRIPTION
Content-Type Yes String Header application/json
Authorization Yes String Header Bearer {oauth2_token}
Tpp-Qwac-Certificate Yes String Header {ttp_uploaded_certificate}
QWAC certificate without line breaks with boundaries
-----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE-----
payment-service Yes String Path Payment service: Possible values is: payments
payment-product Yes String Path The addressed payment product endpoint, e.g. for SEPA Credit Transfers (SCT). The ASPSP will publish which of the payment products/endpoints will be supported. The following payment products is supported: sepa-credit-transfers
paymentId Yes String Path Resource identification of the generated payment initiation resource.
authorisationId Yes String Path Resource identification of the related SCA.
X-Request-ID Yes String Header ID of the request, unique to the call, as determined by the initiating party.

Payment initiation status request

Endpoint

  /psd2/v1/payments/sepa-credit-transfers/{payment_id}/status

Response Body (Example)

  {
    "transactionStatus": "ACCC"
  }

Check the transaction status of a payment initiation.

Request Method
GET

PARAMETER NAME REQUIRED FORMAT AND RULES To DESCRIPTION
Content-Type Yes String Header application/json
Authorization Yes String Header Bearer {oauth2_token}
Tpp-Qwac-Certificate Yes String Header {ttp_uploaded_certificate}
QWAC certificate without line breaks with boundaries
-----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE-----
payment-service Yes String Path Payment service: Possible values is: payments
payment-product Yes String Path The addressed payment product endpoint, e.g. for SEPA Credit Transfers (SCT). The ASPSP will publish which of the payment products/endpoints will be supported. The following payment products is supported: sepa-credit-transfers
paymentId Yes String Path Resource identification of the generated payment initiation resource.
X-Request-ID Yes String Header ID of the request, unique to the call, as determined by the initiating party.

Confirmation of Funds API

The Confirmation of Funds API lets authorised Card Based Payment Instrument Issuers check that Genome customers have enough money for a purchase.

Base URLs
We’ve included the Base URL for Production environment below.
Production https://my.genome.eu/psd2/

Confirmation of Funds Request

Endpoint

  /psd2/v1/funds-confirmations

Request Body (Example)

  {
    "account": {
      "iban": "LT651010019095493166"
    },
    "instructedAmount": {
      "amount": "48.01",
      "currency": "EUR"
    },
    "payee": "Check24"
  }

Response Body (Example)

  {
    "fundsAvailable": false
  }

Creates a confirmation of funds request at the ASPSP.

Request Method
POST

PARAMETER NAME REQUIRED FORMAT AND RULES To DESCRIPTION
Content-Type Yes String Header application/json
Authorization Yes String Header Bearer {oauth2_token}
Tpp-Qwac-Certificate Yes String Header {ttp_uploaded_certificate}
QWAC certificate without line breaks with boundaries
-----BEGIN CERTIFICATE-----your QWAC certificate-----END CERTIFICATE-----
X-Request-ID Yes String Header ID of the request, unique to the call, as determined by the initiating party.

Specifications for batch creation

XML

To send SEPA mass transfer you have to create a credit transfer message based on definitions of elements of the message "pain.001.001.03" (CustomerCreditTransferInitiationV03) of ISO20022 XML standard.

Description of message elements you can find here.

Example .xml format file can be found here.

Make sure that your mass transfer batch must meet the following criteria:

   1. The ISO 20022 XML messages allow for the full range of global language requirements (UTF-8)

   2. You must be able to support the Latin character set commonly used in international communication, as follows: a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9 / - ? : ( ) . , ' + Space

All other characters of the UTF-coding in sent and received payments are converted according to the EPC recommended Conversion table.

   1. Correctness of the message structure.

XML document is described with a scheme written in a specific XSD language (XML Schema Definition). This scheme describes XML Tags, their structure and order. It also may indicate codes which are possible only for specific data, whether data is mandatory or optional, number of possible cases (or repetitions), etc.

  <?xml version="1.0" encoding="UTF-8"?>
  <Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03 pain.001.001.03.xsd">
  <!-- Content of the message -->
  </Document>

The data file which includes message pain.001.001.03 is of the following structure presented at the right side of the screen.

The data file has to contain only one tag with only one XML message, unless the service provider and the client agree otherwise.

The content of the message consists of:

The number of Payment Information and Transaction Information is specified in the Group Header.

CSV

How to use the template.

Please provide information about transfers and beneficiaries into the file - each transfer has its own row. Make sure that you add all required information.

General validation rules:

   1. content type should be text/csv.

   2. the character set is UTF-8.

   3. csv file contains the number of columns as the csv-template required.

   4. each row has the same number of columns as the first row (header) in the file.

   5. consistent values in the same column.

   6. each record should be on a separate line and must start on its own line, but a single record can span multiple lines.

   7. shouldn't be a completely empty row, e.g. blank line or a line where all column values are empty.

   8. shouldn't be 3 identical symbols in a row.

   9. allow specific characters of Lithuanian, German, Dutch and other alphabets.

   10. no missing or stray quote, unclosed quoted field.

   11. a quoted column hasn't leading or trailing whitespace, but spaces which are considered part of a field should not be ignored.

   12. the last field in the record must not be followed by a comma.

Example of .csv format file for SEPA outgoing transfer type:

The uploaded bank transfers csv-batch has the following values:

value format required description example
receiver_iban string max - 64 Mandatory IBAN LT950100100000123456
amount float (0 - 9999999.99) Mandatory Transfer amount 10
currency string (3), ISO 4217 (alfa-3) Mandatory Currency of transfer EUR
transfer_type string (4-6)(alfa) Mandatory Type of transfer method: SEPA or SWIFT SEPA
receiver_acc_country string (3) Mandatory Receiver account country in ISO 3166-1 alpha-3 format
If transfer_type=SWIFT in must be Mandatory		 LTU
receiver_type enum ('PERSONAL' or 'LEGAL') Mandatory LEGAL if receiver is legal entity, PERSONAL if receiver is physical person Personal
transfer_description string (1 - 140) Mandatory Description of the payment Private transfer
receiver_code string (1 - 20) Optional Receiver personal code or receiver company code 54321
receiver_name string (1 - 70) Mandatory Receiver name. Can be as physical person name as legal entity name John Doe
receiver_bic string (max - 32) Mandatory Receiver SEPA BIC or SWIFT code number BANDLT21XXX
transfer_priority enum ('HIGH' or 'NORMAL') Optional HIGH: Processed as a SEPA INSTANT Credit Transfer.
NORMAL: Processed as a SEPA Credit Transfer.
AUTO: Processed based on the following logic:
  • If the amount exceeds the limit, it's processed as a SEPA Credit Transfer.
  • If the amount is within the limit, check if the beneficiary’s BIC is reachable in the INST Participants dictionary. If not, it's processed as a SEPA Credit Transfer; otherwise, it's processed as a SEPA INSTANT Credit Transfer.
'NORMAL' by default if the parameter is not provided		 NORMAL
transfer_perform_date string (YYYY-MM-DD) Conditional Payment execution date. Date when the booking on the bank-side should be executed. If the field is empty, the performance date should be set "today" by default. 2020-12-11
receiver_country string (3) Optional Receivers country in ISO 3166-1 alpha-3 format LTU
receiver_city string (2 - 32) Optional Receiver city Paris
receiver_address string (2 - 64) Optional Receiver address Street, 123
receiver_zip string (2 - 10) Optional Receiver zip 12100
split_to_parts Conditional If transfer_type=SEPA values must be integer, greater than zero and less than '50'. By default=1. If set, amount must be greater than '50'. 1

*INSTANT Credit Transfers will be re-sent to the beneficiary up to 3 times if there is a timeout on the beneficiary's bank side.

The uploaded DIRECT csv-batch has the following values:

value format required description example
Receiver_internal_ID string max - 64 Mandatory Internal user's ID: might be Email or mobile phone number or Genome IBAN or Account ID 1060000034213718
amount float (0 - 9999999.99) Mandatory Transfer amount 10
currency string (3), ISO 4217 (alfa-3) Mandatory Currency of transfer EUR
transfer_type string (4-6) (alfa) Mandatory DIRECT DIRECT
transfer_description string (1 - 140) Mandatory Description of transfer Private transfer
transfer_perform_date string (YYYY-MM-DD) Optional Might be scheduled payment with date of performance in the future. If the field is empty, the performance date should be set "today". 2020-12-11
Cookies
Genome website uses cookies to deliver the best service to you. You can disable cookies at any time. Otherwise, we’ll assume you’re OK to continue. Read more in our Cookie Policy.