Monitor Your Balances

Your Quidkey accounts hold real balances at the payment provider. GET /api/v1/balances returns those balances live, one entry per account and currency — so you can monitor how much is available and alert your team when it runs low. The most common use case is watching the funds available for refunds: the account with the refund role holds the pool customer refunds are paid from. Poll this endpoint on a schedule and raise an alert when that balance drops below your threshold.

Console

View balances in your dashboard

API reference

Full endpoint specification

Account roles

A merchant’s provider-managed accounts are each tagged with a role. Balances are returned per account, because a merchant can hold several — including more than one currency. A merchant with no managed accounts yet receives an empty data array.

Role	Holds
`refund`	The pool customer refunds are paid from — the “available for refunds” figure
`receiving`	Funds that have just landed and are still being processed (in-flight, not yet paid out)

Read the refund row to answer “can I cover refunds right now?”. The receiving balance is money mid-pipeline (about to be converted and paid out) — it is not spendable refund headroom.

Step 1: Fetch balances

Call GET /api/v1/balances with your access token. As a merchant you don’t pass an ID — the account is resolved from your credentials.

Every request needs an Authorization: Bearer <access_token> header. See Authentication to exchange your client_id and client_secret for a token.

curl 'https://core.quidkey.com/api/v1/balances' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

const res = await fetch('https://core.quidkey.com/api/v1/balances', {
  headers: { Authorization: `Bearer ${accessToken}` },
});
const { data } = await res.json();

import requests

res = requests.get(
    'https://core.quidkey.com/api/v1/balances',
    headers={'Authorization': f'Bearer {access_token}'},
)
data = res.json()['data']

A successful response lists one row per account:

{
  "success": true,
  "data": [
    { "id": "a1b2…", "currency": "GBP", "roles": ["refund"],    "balance": "1240.50" },
    { "id": "c3d4…", "currency": "GBP", "roles": ["receiving"], "balance": "5000.00" },
    { "id": "e5f6…", "currency": "EUR", "roles": ["refund"],    "balance": null }
  ]
}

Response fields

Field	Type	Description
`id`	string (uuid)	Unique identifier of the account
`currency`	string	ISO 4217 currency of the account
`roles`	string[]	Account roles (`refund`, `receiving`, …)
`balance`	string \| null	Live decimal balance in the account currency, or `null` when temporarily unavailable

balance is null when the provider did not report a figure for that account (e.g. a freshly provisioned account, or a transient provider hiccup). null means “unknown right now” — it is not zero. Don’t render it as 0, and don’t fire a low-balance alert on it.

Step 2: Alert on a low refund balance

Pick the refund row for the currency you care about and compare it against your threshold:

const res = await fetch('https://core.quidkey.com/api/v1/balances', {
  headers: { Authorization: `Bearer ${accessToken}` },
});
const { data } = await res.json();

const THRESHOLD = 500; // GBP
const refundGbp = data.find(b => b.currency === 'GBP' && b.roles.includes('refund'));

if (refundGbp && refundGbp.balance !== null && Number(refundGbp.balance) < THRESHOLD) {
  await notifyOps(`Refund balance low: £${refundGbp.balance}`);
}

res = requests.get(
    'https://core.quidkey.com/api/v1/balances',
    headers={'Authorization': f'Bearer {access_token}'},
)
data = res.json()['data']

THRESHOLD = 500.0  # GBP
refund_gbp = next(
    (b for b in data if b['currency'] == 'GBP' and 'refund' in b['roles']),
    None,
)

if refund_gbp and refund_gbp['balance'] is not None and float(refund_gbp['balance']) < THRESHOLD:
    notify_ops(f"Refund balance low: £{refund_gbp['balance']}")

Balances are fetched live from the provider on every call. Poll on a sensible cadence (e.g. every few minutes) rather than on every request, and cache the result on your side if you show it in a UI.

Reading another merchant’s balances

Merchant credentials resolve to their own account automatically. If you are a partner or platform acting across merchants, name the target with ?merchant_id=:

GET /api/v1/balances?merchant_id=<merchantId>

As a partner or platform, merchant_id is required — omitting it returns 400 MERCHANT_ID_REQUIRED. You can only read merchants you own; anything else returns 404.

Getting started

Shopify

Embedded Flow (with Stripe)

Payment Links

Payouts

Balances

Console

API reference

Account roles

Step 1: Fetch balances

Response fields

Step 2: Alert on a low refund balance

Reading another merchant’s balances

Next steps

Payout reconciliation

API reference

Console

API reference

​Account roles

​Step 1: Fetch balances

​Response fields

​Step 2: Alert on a low refund balance

​Reading another merchant’s balances

​Next steps

Payout reconciliation

API reference

Account roles

Step 1: Fetch balances

Response fields

Step 2: Alert on a low refund balance

Reading another merchant’s balances

Next steps