Overview

Genome provides customers with functionality that allows them to make payouts.

Payout request format

• JSON-request
  To use JSON type a request header should contain “Content-Type: application/json”, request content should be transmitted as a json-object

Parameters of the payout request via SEPA:

Sample code of the Payout via SEPA request in application/json format with mandatory parameters only:

Copy
{
    "api_version": 1,
    "method": "init",
    "merchant_account": "Account_MP_TRX",
    "merchant_password": "password123",
    "transaction_unique_id": "payout_sepa",
    "amount": 100,
    "currency": "EUR",
    "callback_url": "https://merchant.com/callback",
    "receiver_iban":"1000000001200012",
    "type":"sepa",
    "receiver_bic":"BCXX12345",
    "receiver_name":"John Doe",
    "transfer_description":"Payment for request no. 123456"
}

Sample code of the Payout via SEPA request in application/json format for receiver_type "PERSONAL":

Copy
{
    "api_version": 1,
    "method": "init",
    "merchant_account": "Account_MP_TRX",
    "merchant_password": "password123",
    "transaction_unique_id": "payout_sepa",
    "amount": 100,
    "currency": "EUR",
    "callback_url": "https://merchant.com/callback",
    "receiver_iban":"1000000001200012",
    "type":"sepa",
    "receiver_type":"PERSONAL",
    "receiver_code":"AB12345",
    "receiver_bic":"BCXX12345",
    "receiver_name":"John Doe",
    "transfer_description":"Payment for request no. 123456"
}

Sample code of the Payout via SEPA request in application/json format for receiver_type "LEGAL":

Copy
{
    "api_version": 1,
    "method": "init",
    "merchant_account": "Account_MP_TRX",
    "merchant_password": "password123",
    "transaction_unique_id": "payout_sepa",
    "amount": 100,
    "currency": "EUR",
    "callback_url": "https://merchant.com/callback",
    "receiver_iban":"1000000001200012",
    "type":"sepa",
    "receiver_type":"LEGAL",
    "receiver_code":"AB12345",
    "receiver_bic":"BCXX12345",
    "receiver_name":"Company Ltd.",
    "transfer_description":"Payment for request no. 123456"
}

Response parameters:

Sample code of the Payout via SEPA response in application/json format:

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

Notice: Response with pending status is not a final status of the transaction. The final status of the transaction will be sent in a callback request.

Payout callback

Callback request parameters:

Example of callback request to merchant 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

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

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:

Make notice, that all callback values take a part in 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

Make notice, that a value of the your_privat_signature is provided by Genome integration team.

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.

Transaction statuses

SEPA Payout transaction statuses:

CHECK transaction status

Purpose: Interface should be used to check transaction status.

Gateway supports the CHECK type of transaction requests to provide transaction status information.

Access to CHECK transaction API

The Genome live API can be reached using the following URL:

CHECK transaction request format

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

Notice: In the request, either transaction_unique_id or reference can be used; if both are provided, transaction_unique_id has higher priority.

Sample code of the CHECK request with reference, "application/json" format:

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

Sample code of the CHECK request with transaction id, "application/json" format:

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

transaction_unique_id 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",
    "session_id": "5668fbfb-2d9c-492c-9f7c-11fb8ae9e3fc",
    "transactions": [
        {
            "reference": "ATFF00000000395AD690",
            "transaction_unique_id": "check_request",
            "transaction_type": "PAYOUT",
            "status": "SUCCESS",
            "code": 0,
            "message": "SUCCESS",
            "token": "5519225d-3460-433f-ad4e-62649d0bb909",
            "timestamp": 1529796980
        }
    ],
    "status": "success",
    "code": 0,
    "message": "Transaction processed successfully"
}

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

Query on Demand API: Transactions

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

The Genome live query on demand API can be reached using the following URL:

Note: that the https://api.genome.eu/api/mp/transactions URL provides the transaction amount, including the SEPA Payout fee. Use the https://api.genome.eu/api/mp/transactions/ra URL to get information about the transaction amount, excluding the SEPA Payout fee. You can use the same request payload for the same response - the only different variable will be the amount.

QoD Request format

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

Response parameters:

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

Copy
{
    "api_version": 1,
    "timestamp": 1545117788.019275,
    "session_id": "de7a5f-67f1-5c18a05b-167c0326604-113b",
    "merchant_account": "Account_MP_TRX",
    "transactions": [
        {
            "transaction_type": "PAYOUT",
            "status": "SUCCESS",
            "mode": "CC",
            "reference": "ATFF00000000395376F6",
            "amount": 10,
            "currency": "GBP",
            "merchant": null,
            "user": null,
            "card": null,
            "bank": null,
            "time": 1520447215.4163,
            "token": "54817d79-8b5c-4c6f-a266-7f2264ed02ad",
            "transaction_unique_id": "accept.1420447212.1505680771",
            "code": 0,
            "message": "SUCCESS"
        }
    ],
    "status": "success",
    "code": 0,
    "message": "Transaction processed successfully"
}