Sign In

Settlement List

Fetch a merchant's settlements for a given process date.

POST/v1/route/settlement-list

Returns the settlements for a merchant on the requested process_date. On the first call for a date, GrowthBnk fetches the settlements from the payment gateway and stores them; subsequent calls for the same date are served from GrowthBnk without calling the gateway again. Authenticated the same way as the other key/hash APIs — the key and hash travel in the request headers.

Authentication & Hash Generation

This endpoint is authenticated with your API key plus a per-request SHA-256 hash. Send the key in the X-API-Key header and the hash in the Hash header.

Hash formula

Hash = SHA256(key | process_date | salt), joined with the | character. The salt is your merchant secret key — it is used only to compute the hash and must never be sent in the request. See the Authentication guide.

Request Headers

HeaderTypeRequiredDescription
X-API-KeystringRequiredYour merchant API key.
HashstringRequiredSHA-256 auth hash — SHA256(key | process_date | salt).
Content-TypestringRequiredMust be application/json.

Request Payload

Field NameData TypeRequiredDescriptionAllowed ValuesExample
process_date Date Required Settlement processing date to fetch settlements for. Also included in the auth hash. Format YYYY-MM-DD 2026-07-13

Sample Request

Compute the hash, then POST the JSON body:

Request
# 1. Compute the auth hash: sha256(key|process_date|salt)
API_KEY="YOUR_API_KEY"
API_SALT="YOUR_API_SALT"
PROCESS_DATE="2026-07-13"
HASH=$(printf '%s' "$API_KEY|$PROCESS_DATE|$API_SALT" | openssl dgst -sha256 | awk '{print $2}')

# 2. Call the API (key + hash travel in the request headers)
curl -X POST "https://api.growthbnk.com/v1/route/settlement-list" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -H "Hash: $HASH" \
  -d '{
    "process_date": "'"$PROCESS_DATE"'"
  }'
import hashlib
import requests

API_KEY = "YOUR_API_KEY"
API_SALT = "YOUR_API_SALT"
BASE_URL = "https://api.growthbnk.com"

process_date = "2026-07-13"

# Auth hash: sha256(key|process_date|salt)
signing = f"{API_KEY}|{process_date}|{API_SALT}"
auth_hash = hashlib.sha256(signing.encode("utf-8")).hexdigest()

response = requests.post(
    f"{BASE_URL}/v1/route/settlement-list",
    json={"process_date": process_date},
    headers={
        "Content-Type": "application/json",
        "X-API-Key": API_KEY,
        "Hash": auth_hash,
    },
    timeout=30,
)
print(response.status_code, response.json())
<?php
$apiKey  = 'YOUR_API_KEY';
$apiSalt = 'YOUR_API_SALT';
$baseUrl = 'https://api.growthbnk.com';

$processDate = '2026-07-13';

// Auth hash: sha256(key|process_date|salt)
$signing  = "{$apiKey}|{$processDate}|{$apiSalt}";
$authHash = hash('sha256', $signing);

$ch = curl_init("{$baseUrl}/v1/route/settlement-list");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        "X-API-Key: {$apiKey}",
        "Hash: {$authHash}",
    ],
    CURLOPT_POSTFIELDS     => json_encode(['process_date' => $processDate]),
]);
$response = curl_exec($ch);
echo $response;

Request body

Request body
{
    "process_date": "2026-07-13"
}

Response Format

A successful call returns HTTP 200 OK with the settlements for the date.

FieldTypeDescription
successbooleanAlways true on success.
messagestringHuman-readable status message.
countintegerNumber of settlements returned.
dataarrayList of settlement objects (fields below).
data[].settlement_idstringGrowthBnk settlement id.
data[].gateway_settlement_idstringSettlement id from the payment gateway.
data[].settlement_statusstringSettlement status (e.g. SETTLED).
data[].settlement_typestringSettlement type.
data[].is_settledbooleanWhether the settlement is complete.
data[].currencystringCurrency code.
data[].total_transaction_amountstringGross transaction amount for the settlement.
data[].settlement_amountstringNet amount settled to the merchant.
data[].settlement_chargesstringGateway/service charges deducted.
data[].service_taxstringTax deducted.
data[].utr_numberstring | nullBank UTR / payout reference.
data[].settlement_datestringISO-8601 settlement timestamp.
data[].settlement_initiated_onstring | nullISO-8601 time the settlement was initiated.
data[].payout_amountstring | nullAmount paid out to the merchant bank account.

Sample Success Response

Success
200 OK
{
    "success": true,
    "message": "Settlements fetched successfully",
    "count": 1,
    "data": [
        {
            "settlement_id": "STL20260713120000123",
            "gateway_settlement_id": "setl_NabC123XyZ",
            "settlement_status": "SETTLED",
            "settlement_type": "regular",
            "is_settled": true,
            "currency": "INR",
            "total_transaction_amount": "10000.00",
            "settlement_amount": "9800.00",
            "settlement_charges": "170.00",
            "service_tax": "30.00",
            "utr_number": "UTR123456789",
            "settlement_date": "2026-07-13T18:30:00Z",
            "settlement_initiated_on": "2026-07-13T10:00:00Z",
            "payout_amount": "9800.00"
        }
    ]
}

Error Responses

Validation error
400 Bad Request
{
    "success": false,
    "message": {
        "process_date": [
            "This field is required."
        ]
    }
}
Invalid hash
401 Unauthorized
{
    "detail": "Invalid authentication hash."
}
Unauthorized (merchant not found)
401 Unauthorized
{
    "detail": "Unauthorized."
}
Internal server error
500 Internal Server Error
{
    "success": false,
    "message": "Internal server error"
}

Status Codes

StatusMeaning
200 OKSettlements fetched successfully.
400 Bad RequestMissing or invalid process_date (validation error).
401 UnauthorizedMissing/invalid API key or mismatched authentication hash.
500 Internal Server ErrorUnexpected server error.

Error Codes

StatusMessageReason
400Validation errorprocess_date is missing or not a valid YYYY-MM-DD date.
401Invalid authentication hash.Computed hash does not match key|process_date|salt.
401Unauthorized.No merchant is registered for the supplied API key, or the key/hash headers are missing.
500Internal server errorAn unexpected error occurred while fetching settlements.

Notes