Genome Documentation

SEPA Payout API

Overview

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

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

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:

Parameter name	Required	Format and rule	Description
api_version	Yes	*int* Possible value: 1	API version
merchant_account	Yes	*string* (6-32)	Merchant account
merchant_password	Yes	*string* (6-32)	Account password
method	Yes	*string* Possible value: init	Method for the payout request
transaction_unique_id	Yes	*string* (1-45)	Transaction unique identifier in Merchant 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
type	Yes	*string* Possible value: sepa	Type of the payout method
receiver_iban	yes	*string* max - 64	Receiver IBAN number
receiver_type	conditional	*enum* ('PERSONAL', 'LEGAL')	Mandatory if parameter receiver_code is provided, otherwise parameter is optional LEGAL if receiver is legal entity PERSONAL if receiver is physical person
receiver_code	optional	*string* (1 - 20)	Receiver personal code or receiver company code
receiver_name	yes	*string* (1 - 70)	Receiver name. Can be as physical person name as legal entity name
receiver_bic	yes	*string* (max - 32)	Receiver SEPA BIC number
transfer_description	yes	*string* (1 - 140)	Payment purpose
transfer_priority	optional	*enum* ('HIGH', 'NORMAL')	Will be 'NORMAL' by default if the parameter is not provided
transfer_perform_date	optional	*string* (YYYY-MM-DD)	Payout execution date. Date when the booking on the bank-side should be executed
receiver_address	optional	*string* (2 - 64)	Receiver address
receiver_city	optional	*string* (2 - 32)	Receiver city
receiver_country	optional	*string* (3)	Receivers country in ISO 3166-1 alpha-3 format
receiver_zip	optional	*string* (2 - 10)	Receiver zip
receiver_email	optional	*string* (6 - 255)	Receiver email address
receiver_ip	optional	*string* (IPv4, IPv6)	Receiver IP address. Not all acquirers support IPv6 format
receiver_id	optional	*string* (1 - 60)	Customer Id on merchant's side
receiver_phone	optional	*string* (7 - 15)	Receiver phone number

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

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

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

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

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

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

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

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

Payout callback

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* (1-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

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

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.

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:

Status	Description
SUCCESS	transaction processed successfully
ERROR	transaction error
DECLINED	transaction declined
PENDING	transaction processing
FRAUDED	transaction fraud

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:

Web Service	URL
Live Genome Gateway API Service	https://api.genome.eu/api/mp/transaction

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:

Parameter name	Required	Format and rule	Description
api_version	Yes	*int* Possible value: 1	API version
merchant_account	Yes	*string* (6-32)	Merchant account
merchant_password	Yes	*string* (6-32)	Account password
transaction_type	Yes	*string* Possible value: CHECK	Type of the transaction: CHECK
transaction_unique_id	Yes	*string* (1-45)	Unique transaction id

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

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

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

Parameter name	Format and rule	Description
api_version	*float* Possible value: 1	API version
merchant_account	*string* (6-32)	Merchant account
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* (1-45)	Unique transaction Id
transaction_type	*string* Possible value: PAYOUT	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 value: 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

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

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:

Web Service	URL
Live QOD Service	https://api.genome.eu/api/mp/transactions

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 account
transactions	Yes	array	Contains of transactions data
transaction_type	Yes	*string* Possible value: PAYOUT	Type of the transaction: CHECK
status	Yes	*string* Possible value: SUCCESS, DECLINED, ERROR, MALFORMED, FRAUDED, CHARGEDBACK, REFUNDED, VOIDED, PARTIAL-REFUNDED, WRONGREF	Status of the transaction
mode	Yes	*string* Possible value: 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 account
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* (2-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* (1-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": "de7a5f-67f1-5c18a05b-167c0326604-113b",
    "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"
}

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:

Parameter name	Required	Format and rule	Description
api_version	Yes	*float* (1) Possible value: 1	API version
merchant_account	Yes	*string* (6-32)	Merchant account
merchant_password	Yes	*string* (6-32)	Account 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 value: transactions	Transaction types is used for the request: transactions
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

Genome Documentation

SEPA Payout API

SEPA Payout API

Overview

Payout request format

Payout callback

checkSum calculation

Transaction statuses

CHECK transaction status

Query on Demand API: Transactions

QoD Request format

Response codes

Specifications for batch creation

On this page