GoCardlessDeveloper Docs
Create a sandbox account

Balance

View as Markdown

Returns the balances for a creditor. These balances are the same as what’s shown in the dashboard with one exception (mentioned below under balance_type).

These balances will typically be 3-5 minutes old. The balance amounts likely won’t match what’s shown in the dashboard as the dashboard balances are updated much less frequently (once per day).

List balances#

GET/balances

Returns a cursor-paginated list of balances for a given creditor. This endpoint is rate limited to 60 requests per minute.

GET https://api.gocardless.com/balances?creditor=CR123 HTTP/1.1
@client.balances.list(
  params: {
    creditor: "CR123",
  }
).records
client.balances.list(params={
  "creditor": "CR123",
}).records
await client.balances.list({
  creditor: "CR123",
});
$client->balances()->list([
  "params" => [
    "creditor" => "CR123",
  ]
]);
client.balances().
  all().
  withCreditor("CR123").
  execute();
params := gocardless.BalanceListParams{
  Creditor: "CR123",
}

response, err := client.Balances.List(ctx, params)
var request = new GoCardless.Services.BalanceListRequest()
{
  Creditor = "CR123",
};

client.Balances.All(request);
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "balances": [
    {
      "balance_type": "pending_payments_submitted",
      "amount": 365000,
      "currency": "EUR",
      "last_updated_at": "2025-03-17T11:08:04.926Z",
      "links": {
        "creditor": "CR123"
      }
    },
    {
      "balance_type": "pending_payouts",
      "amount": 0,
      "currency": "EUR",
      "last_updated_at": "2025-03-17T11:48:14.416Z",
      "links": {
        "creditor": "CR123"
      }
    },
    {
      "balance_type": "confirmed_funds",
      "amount": 421198,
      "currency": "EUR",
      "last_updated_at": "2025-03-17T11:15:52.201Z",
      "links": {
        "creditor": "CR123"
      }
    }
  ],
  "meta": {
    "cursors": {
      "before": null,
      "after": null
    },
    "limit": 50
  }
}
Response 200

Successful response

balancesarray
5 properties
balance_typestring

Type of the balance. Could be one of

  • pending_payments_submitted: Payments we have submitted to the scheme but not yet confirmed. This does not exactly correspond to Pending payments in the dashboard, because this balance does not include payments that are pending submission.
  • confirmed_funds: Payments that have been confirmed minus fees and unclaimed debits for refunds, failures and chargebacks. These funds have not yet been moved into a payout.
  • pending_payouts: Confirmed payments that have been moved into a payout. This is the total due to be paid into your bank account in the next payout run (payouts happen once every business day). pending_payouts will only be non-zero while we are generating and submitting the payouts to our partner bank.
confirmed_fundspending_payoutspending_payments_submitted
amountinteger

The total amount in the balance, defined as the sum of all debits subtracted from the sum of all credits, in the lowest denomination for the currency (e.g. pence in GBP, cents in EUR).

currencystring

ISO 4217 currency code. Currently "AUD", "CAD", "DKK", "EUR", "GBP", "NZD", "SEK" and "USD" are supported.

AUDCADDKKEURGBPNZDSEKUSD
last_updated_atstring

Dynamic timestamp recording when this resource was last updated.

linksobject
1 properties
creditorstring

ID of the associated creditor.

metaobject
2 properties
limitinteger
cursorsobject
2 properties
beforestring

Cursor pointing to the end of the desired set.

afterstring

Cursor pointing to the start of the desired set.

Errors 400401404422500
400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body
codeinteger
documentation_urlstring
errorsarray
2 properties
reasonstring
messagestring
messagestring
request_idstring
typestring
metadataobject
linksobject
SupportDashboard