Overview

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

Card payouts are available only for merchants whose country of business registration is one of the following: Austria, Belgium, Denmark, Estonia, Finland, France, Germany, Hungary, Ireland, Italy, Malta, Netherlands, Norway, Poland, Portugal, Spain, Sweden, Switzerland, UK. For other merchants, a payout request is rejected with code 3116 (MID does not support the country).

The payout amount and fees are reserved from your merchant balance; if the balance is insufficient, the payout fails with code 3101.

Payout request formats

• POST-request
  To use the JSON type, a request header should contain "Content-Type: application/json". The request content should be transmitted as a json-object as in the samples below. application/x-www-form-urlencoded is not supported.

Payout on credit card

Parameters of the payout request on credit card via the full credit card data:

Sample code of the payout by credit card request in the application/json format:

Copy
{
    "api_version": 1,
    "method": "init",
    "merchant_account": "Account_MP_TRX",
    "merchant_password": "password123",
    "transaction_unique_id": "payout_via_cc",
    "amount": 10,
    "currency": "USD",
    "callback_url": "https://merchant.com/callback",
    "user_id": "user123",
    "user_ip": "127.0.0.1",
    "user_email": "john.doe@example.com",
    "card": {
        "card_cvv": "029",
        "card_number": "4012000300001003",
        "card_holder": "John Doe",
        "card_exp_year": "2030",
        "card_exp_month": "07"
    }
}

Response parameters:

Sample code of the payout by credit card response in the application/json format:

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

Notice: In case of a successful request, the merchant will receive status=pending and code=0 in response. Be advised that the final status of the payout request will be received by the merchant in the callback data. More details regarding callback data are provided below.

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

Notice: The payout response carries no reference; correlate by your transaction_unique_id. The Genome reference is sent in the callback. Ignore unknown custom_* fields.

Payout via token

Payout via token is not currently supported.

A merchant can use a token value instead of full credit card data. A token is hashed data of the credit card. The token value contains the credit card number, expiry date, and cardholder name.

Parameters of the payout request on credit card via token:

Sample code of the payout by token request in the application/json format:

Copy
{
    "api_version": 1,
    "method": "init",
    "merchant_account": "Account_MP_TRX",
    "merchant_password": "password123",
    "transaction_unique_id": "payout_via_token",
    "amount": 10,
    "currency": "USD",
    "callback_url": "https://merchant.com/callback",
    "user_id": "user123",
    "user_ip": "127.0.0.1",
    "user_email": "john.doe@example.com",
    "card": {
        "token": "5aaaa194-1d68-4ef8-a72f-009184ee03a6",
        "card_holder": "John Doe"
    }
}

Response parameters:

Sample code of the payout by token response in the application/json format:

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

Notice: In case of a successful request, the merchant will receive status=pending and code=0 in response. Be advised that the final status of the payout request will be received by the merchant in the callback data. More details regarding callback data are provided below.

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

Notice: The payout response carries no reference; correlate by your transaction_unique_id. The Genome reference is sent in the callback. Ignore unknown custom_* fields.

Payout callback

Callback request parameters:

Example of the callback request to merchant in the "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 the merchant in application/x-www-form-urlencoded format. The callback is received by the merchant when, in response, Genome gets the code - 200 (it's required) and body text - OK (it's optional). In other cases, the callback is not received by the merchant, and Genome will try to re-send the callback data periodically. The number of attempts is limited.

A callback is sent when the payout reaches a final status: success, decline, or error. Requests that were rejected synchronously (status error in the response) produce no callback.

To check a payout, send a host-to-host CHECK request with your transaction_unique_id.

checkSum calculation

The checkSum calculation allows comparing the value of the checkSum in the callback request with own calculation.

The 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 of the checkSum callback, use the algorithm described below:

Note that all callback values take part in the calculation of the checkSum parameter.

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

Note that the value of the your_private_signatureis your current merchant account password.

If you fully translate the callback shown in the example into the line, you get:

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

• The next step is to calculate the hash for the obtained line by hash sha256, the result should match the line transferred 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_private_signature');

• If the values coincide, the signature is valid.

Transaction statuses

Payout transaction statuses:

Payout response codes

List of the response codes for payout transactions:

Module	Code	Message (can be extended depending on the case)
Payout	1	GENERAL SYSTEM ERROR
	11	INTERNAL SERVICE TIMEOUT
	1004	INVALID PARAMETER (message: '<field>: <reason>')
	2001	INVALID MERCHANT ACCOUNT OR PASSWORD
	2003	MERCHANT ACCOUNT IS NOT ACTIVE
	2009	MERCHANT NOT ACTIVE
	3000	GENERAL PROCESSING ERROR
	3001	TRANSACTION ID DUPLICATE
	3015	INVALID CURRENCY
	3101	INSUFFICIENT FUNDS
	3113	TRANSACTION NOT SUPPORTED BY MID
	3116	COUNTRY NOT SUPPORTED BY MID

Acquirer decline codes can also be returned; see the Response codes page.