Host to host API

Overview

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

• AUTH – authorization allows freezing certain amount on card account during 7 days (depends on acquirer side), until AUTH will be settled or voided. AUTH will be automatically voided after 7 days (depends on acquirer side) by Genome. The period during which AUTH remains active can be changed due to card association’s regulations.

• AUTH3D – 3D Secure authorization is available for the account which configured to support 3D secure. This transaction type will initiate 3DS flow.

• SALE – the basic function which allows collecting money directly from cardholder account. After Sale executed successfully it can be only Refunded by Merchant or Charge backed by the Issuing bank. This transaction type can be used in 3DS flow.

• SALE3D – the complex transaction includes 3D secure 3DS Authorization transaction and SALE transaction, is available for the account which configured to support 3D secure. This transaction type will initiate 3DS flow.

• REFUND – a request instructing the Genome Gateway to refund a previously settled Transaction. A settled transaction can be partly or fully refunded. This Transaction is used to refund Customers and is initiated following his request or the Merchant’s needs. However, it is not possible to refund the same Transaction more than once.

• VOID – the Void Transaction enables the Merchant to back out of an erroneous or problematic Transaction before it is settled or credited. As the Voided Transaction is cancelled before it is sent to the Acquirer bank, it will not appear in the Customer's CC statement, nor will the original Transaction cancelled.

• SETTLE - a request instructing the Genome Gateway to settle a previously-authorized Transaction, i.e. transfer the funds from the Customer’s bank account to the Merchant’s bank account. This Transaction is always preceded by an Auth Transaction.

• CHECK – a request is used to check Transaction status.

Other definitions:

• ECI - Electronic Commerce Indicators the security level associated with an Internet purchase transaction. The Gateway will return an ECI in the message which the merchant can use to gauge risk associated with the transaction. The Genome Gateway will process the ECI to the acquirer or its processor for inclusion in the authorization request message.

ECI VALUES

Access to Genome Gateway API

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

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

• 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

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

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

AUTH transaction

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

Request parameters:

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

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

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.

Response parameters:

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

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

After the AUTH transaction has been processed a merchant have to send the following transactions:

• SETTLE
• VOID
• CHECK

AUTH (by token) transaction

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

Request parameters:

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

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

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.

Response parameters:

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

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

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

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

Request parameters:

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

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

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.

Response parameters:

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

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

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

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:

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

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

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.

Response parameters:

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

Copy
{
    "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,
    "eci": 5,
    "acs_url": "https://acs.bank.com/authentication",
    "authcode": "",
    "status": "success",
    "code": 0,
    "message": "Transaction processed successfully"
}

Callback

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:

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

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

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

Copy
<?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.

• excluded from the array checkSum field, then sort the array by key in the alphabetical order, form a line on the principle: key1 = value1 | key2 = value2 | switchN = valueN | your_private_signature from the sorted array

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:

• code=0|message=Transaction processed successfully|reference=PTFF00000061B7146A8B|status=success|token=43d206b5-af88-4770-9d08-0c7eb17b000|transaction_unique_id=000453542|your_privat_signature

• The next step is to calculate hash for the obtained line by hash sha256, the result should match the line transfered in checkSum field. $countedCheckSum = hash('sha256','code=0|message=Transaction processed successfully|reference=PTFF00000061B7146A8B|status=success|token=43d206b5-af88-4770-9d08-0c7eb17b000|transaction_unique_id=000453542|your_privat_signature');

• If the values coincide - the signature is valid.

SALE transaction

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:

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

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

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.

Response parameters:

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

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

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

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

Request parameters:

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

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

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

Response parameters:

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

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

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

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

Request parameters:

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

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

Response parameters:

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

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

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

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

Request parameters:

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

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

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

Response parameters:

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

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

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

Purpose: Interface should be used to check transaction status.

Request parameters:

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

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

transaction_unique_id or reference can be passed for CHECK request.

Response parameters:

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

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

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.

Validation exposition: MDN web docs