Query on demand API

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

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

Prev

Payout API

Next

Response codes

On this page