Payout API

Overview

Genome provides merchants functionality which allows to make payouts to their customers.

Payout 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

Payout on credit card

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

Sample code of the Payout by Credit card request in 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": "2022",
        "card_exp_month": "07"
    }
}

Response parameters:

Sample code of the Payout by Credit card response in application/json format:

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

Notice: in case of successful request merchant will receive status=pending and code=0 in response. Be advised that the final status of the payout request merchant will receive in callback data, more details regarding callback data is provided below.

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

Payout via Token

Merchant can use Token value instead of full credit card data. Token is hashed data of the credit card. Token value contains of credit card number, expiry date and card holder name.

Parameters of the payout request on credit card via Token:

Sample code of the Payout by Token request in 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 application/json format:

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

Notice: in case of successful request merchant will receive status=pending and code=0 in response. Be advised that the final status of the payout request merchant will receive in callback data, more details regarding callback data is provided below.

Notice: Response is not a finished status of the transaction. Finished status will be sent in 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 your current merchant account password

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

Payout transaction statuses:

Payout response codes

List of the response codes for payout transactions: