Genome Documentation

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

POST-request
To use POST type a request header should contain “Content-Type: application/x-www-form-urlencoded”, request content should be transmitted as a serialized string key1=value1&key2=value2
JSON-request
To use JSON type a request header should contain “Content-Type: application/json”, request content should be transmitted as a json-object

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	no¹	*string* Possible values: acs, desc	Ordering ASC (by default)/DESC
page	no²	*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	no³	*string* (1-1000)	Quantity of the fetched transactions. 1000 by default. Can’t be greater than 1000

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

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.

QoD Response formats

JSON-document is used by default

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

Transactions

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

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

Chargebacks

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

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

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

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

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

Response statuses

Code	Description
success	Successful QOD response
error	Unsuccessful 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

Genome Documentation

Query on demand API

Query on demand API

Access to Genome Qod API

QoD Workflow

QoD Request formats

QoD Response formats

Transactions

Chargebacks

Request validation specified (not API) response codes

Empty response

Erroneous response

Response statuses

QoD API specified response codes

Payout API

Response codes

On this page