BizKitHub
DocsAPI ReferencePayment Gateway/bff/payment-gateway/monthly-analytics
getPayment GatewayAdmin BFF

/bff/payment-gateway/monthly-analytics

Order-level (NOT payment-level) roll-up. Each qualifying order counts once, bucketed by the month of its FIRST payment attempt through this gateway. Storno orders (shop__order_status.type_id = 3) are excluded entirely. An order counts as a success if ANY of its payments succeeded (PAID / COMPLETE), even if earlier attempts failed — so retries don't inflate the "leaked" bucket. Amounts: receivedAmount = first successful payment's price; potentialAmount = first attempt's price; lostAmount = first attempt's price for orders that ended up failed (no success, no pending). Only direction = 'in' payments contribute.

Payment GatewaygetBffPayment-gatewayMonthly-analytics

Parameters

2 query

Query parameters

· 2
codestringRequired

Gateway instance code/slug.

Examplecomgate-smichov
monthCountstringOptional

How many calendar months to return (default 24, clamped to [1, 240]). The window always ends with the current month and is automatically clamped down to the first month with any payment activity — so a gateway younger than monthCount months reports only as many buckets as actually exist.

Example12

Response schema

1 status code documented

200SuccessPer-month performance roll-up for a single payment-gateway instance.
gatewayCodestringRequired

Gateway instance code/slug echoed back for client-side cache keys.

gatewayNamestringRequired

Human-readable provider name (GoPay, Comgate, Stripe).

currencystringRequired

Organisation's default currency code — all amounts are reported as raw numbers in this currency.

monthCountnumberRequired

Effective number of months returned. May be lower than the requested value when the gateway is younger than the requested window.

monthsobject[]Required
Each array item:
monthstringRequired

YYYY-MM bucket identifier.

totalCountnumberRequired

Distinct non-storno orders whose FIRST payment attempt through this gateway landed in this month.

successCountnumberRequired

Orders in this bucket that eventually got paid (any payment succeeded).

failedCountnumberRequired

Orders with no success and no pending payment — the true "leaked" bucket.

pendingCountnumberRequired

Orders with no success yet, but at least one payment is still open.

receivedAmountnumberRequired

SUM of the first successful payment's price across successful orders in this bucket.

potentialAmountnumberRequired

SUM of first-attempt prices across ALL orders in this bucket — the ceiling we tried to collect.

lostAmountnumberRequired

SUM of first-attempt prices across FAILED orders in this bucket. Pending orders contribute 0.

successRatePctnumberRequired

successCount / totalCount × 100. Zero when there are no orders in the bucket.

averageSuccessfulAmountnumberRequired

AVG(first-successful-payment price) across successful orders. Zero when there were none.

averageAttemptAmountnumberRequired

AVG(first-attempt price) across all qualifying orders. Zero when there were none.

totalsobjectRequired
totalCountnumberRequired
successCountnumberRequired
failedCountnumberRequired
pendingCountnumberRequired
receivedAmountnumberRequired
potentialAmountnumberRequired
lostAmountnumberRequired
successRatePctnumberRequired

Window-wide success rate.

averageSuccessfulAmountnumberRequired
averageAttemptAmountnumberRequired
monthlyAverageReceivednumberRequired

Arithmetic mean of monthly receivedAmount. Used as the chart's "average" reference line.

monthlyMedianReceivednumberRequired

Median of monthly receivedAmount. Used as the chart's "median" reference line.

monthlyAverageSuccessRatePctnumberRequired

Arithmetic mean of monthly successRatePct, computed only over months with at least one attempt.

monthlyMedianSuccessRatePctnumberRequired

Median of monthly successRatePct, computed only over months with at least one attempt.

bestMonthobject | nullRequired

Month with the highest receivedAmount in the window. Null when there were no attempts.

One of 2:
Variant 1
monthstringRequired
receivedAmountnumberRequired
Variant 2
null
worstMonthobject | nullRequired

Month with the lowest receivedAmount (among months that had at least one attempt). Null when there were none.

One of 2:
Variant 1
monthstringRequired
receivedAmountnumberRequired
Variant 2
null

Response example

application/json
{
  "gatewayCode": "example_gatewayCode",
  "gatewayName": "example_gatewayName",
  "currency": "example_currency",
  "monthCount": 0,
  "months": [
    {
      "month": "example_month",
      "totalCount": 0,
      "successCount": 0,
      "failedCount": 0,
      "pendingCount": 0,
      "receivedAmount": 0,
      "potentialAmount": 0,
      "lostAmount": 0,
      "successRatePct": 0,
      "averageSuccessfulAmount": 0,
      "averageAttemptAmount": 0
    }
  ],
  "totals": {
    "totalCount": 0,
    "successCount": 0,
    "failedCount": 0,
    "pendingCount": 0,
    "receivedAmount": 0,
    "potentialAmount": 0,
    "lostAmount": 0,
    "successRatePct": 0,
    "averageSuccessfulAmount": 0,
    "averageAttemptAmount": 0,
    "monthlyAverageReceived": 0,
    "monthlyMedianReceived": 0,
    "monthlyAverageSuccessRatePct": 0,
    "monthlyMedianSuccessRatePct": 0
  }
}

Request example

GET /bff/payment-gateway/monthly-analytics

get
curl -X GET "https://api.bizkithub.com/bff/payment-gateway/monthly-analytics?code=comgate-smichov&monthCount=12" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Need an API key?

All BizKitHub public API endpoints require authentication via API key.

Get API Key