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. You have one account with the refund role in each currency you are paid out in, and a refund is paid from the one in the currency its payment was paid out in. Poll this endpoint on a schedule and raise an alert when one of those balances 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`	Funds for refunds of payments paid out in this currency — the “available for refunds” figure for that currency
`receiving`	Funds that have just landed and are still being processed (in-flight, not yet paid out)

Read the refund row in a payment’s payout currency to answer “can I cover a refund of this payment right now?”. A refund of a payment paid out in GBP comes from the GBP refund account, whatever currency the customer paid in. 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

Each payout currency has its own refund row, so check each currency you are paid out in. This example checks GBP:

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