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	*float* 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	*string* Starting with 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
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

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* (max - 36)	Unique session Id of the request
timestamp	*integer* unix timestamp	Payout API response time
status	*string* Possible values: pending, 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:

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

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, DECLINED, ERROR, FRAUDED	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	*float* 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	Conditional	*string* (1-45)	Unique transaction id
reference	Conditional	*string* (max - 20)	Unique transaction id

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:

{
    "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
session_id	*string* (max - 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, DECLINED, ERROR, FRAUDED, PENDING	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
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",
    "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:

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

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	*int* (unix timestamp)	Processing transaction time FROM
time_to	Yes	*int* (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	*int* Possible value: starting from 1	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	*int* (1-1000)	Quantity of the fetched transactions. 1000 by default. Can’t be greater than 1000

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* (max - 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: PAYOUT
status	Yes	*string* Possible value: SUCCESS, DECLINED, ERROR, FRAUDED, PENDING	Status of the transaction
mode	Yes	*string* Possible value: CC	Transaction mode.
reference	Yes	*string* (20)	Reference of the transaction in Genome system.
amount	Yes	*float* (0-9999999.9999)	Transaction amount
currency	Yes	*string* (3) ISO 4217 (alfa-3)	Transaction currency
change_reason_type	optional	*string*	It helps to analyze the reason of change status for a transaction after RDR modification
merchant	optional	*array* or *null*	Contains of merchant data
user	optional	*array* or *null*	Contains of user data
card	optional	*array* or *null*	Contains of customer's card data
bank	optional	*array* or *null*	Contains of acquirer data
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.
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": "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"
}

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