Balances & Transactions

Retrieve real-time account balances and a filterable history of transactions for a consented account.

Integration guide

Goal: Fetch a point-in-time balance and a filtered transaction history for a customer's account.

Estimated time: 20 minutes

Prerequisites

Sandbox credentials and an access token
An account ID from the Accounts endpoint

Balances

Returns the account's balance at a moment in time, across balance types such as available, credit, and reserved.

curl "https://sandbox.sparefinancial.sa/api/v1.0/ais/Balance/Get?accountId=ACCOUNT_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

const res = await fetch(
  "https://sandbox.sparefinancial.sa/api/v1.0/ais/Balance/Get?accountId=ACCOUNT_ID",
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  },
);

const balance = await res.json();

res = requests.get(
    "https://sandbox.sparefinancial.sa/api/v1.0/ais/Balance/Get",
    params={"accountId": "ACCOUNT_ID"},
    headers={
        "Authorization": f"Bearer {access_token}",
    },
)

balance = res.json()

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://sandbox.sparefinancial.sa/api/v1.0/ais/Balance/Get?accountId=ACCOUNT_ID"))
    .header("Authorization", "Bearer " + accessToken)
    .GET()
    .build();

HttpResponse<String> response = client.send(
    request, HttpResponse.BodyHandlers.ofString());

String balance = response.body();

using var client = new HttpClient();

var request = new HttpRequestMessage(
    HttpMethod.Get,
    "https://sandbox.sparefinancial.sa/api/v1.0/ais/Balance/Get?accountId=ACCOUNT_ID");
request.Headers.Add("Authorization", $"Bearer {accessToken}");

var response = await client.SendAsync(request);

var balance = await response.Content.ReadAsStringAsync();

req, _ := http.NewRequest(
    http.MethodGet,
    "https://sandbox.sparefinancial.sa/api/v1.0/ais/Balance/Get?accountId=ACCOUNT_ID",
    nil,
)
req.Header.Set("Authorization", "Bearer "+accessToken)

res, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer res.Body.Close()

balance, _ := io.ReadAll(res.Body)

Transactions

Returns financial movements, deposits, withdrawals, and payments, each with date, amount, description, and related details. See the full shape in Transaction Data Object.

Filters

Filter	Options
Type	`Credit` (incoming) / `Debit` (outgoing)
Status	`Pending`, `Booked`, `InterimPending`
Date range	`fromBookingDateTime` → `toBookingDateTime`

curl -X POST "https://sandbox.sparefinancial.sa/api/v1.0/ais/Transaction/List?accountId=ACCOUNT_ID&consentId=CONSENT_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

const res = await fetch(
  "https://sandbox.sparefinancial.sa/api/v1.0/ais/Transaction/List?accountId=ACCOUNT_ID&consentId=CONSENT_ID",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  },
);

const transactions = await res.json();

res = requests.post(
    "https://sandbox.sparefinancial.sa/api/v1.0/ais/Transaction/List",
    params={"accountId": "ACCOUNT_ID", "consentId": "CONSENT_ID"},
    headers={
        "Authorization": f"Bearer {access_token}",
    },
)

transactions = res.json()

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://sandbox.sparefinancial.sa/api/v1.0/ais/Transaction/List?accountId=ACCOUNT_ID&consentId=CONSENT_ID"))
    .header("Authorization", "Bearer " + accessToken)
    .POST(HttpRequest.BodyPublishers.noBody())
    .build();

HttpResponse<String> response = client.send(
    request, HttpResponse.BodyHandlers.ofString());

String transactions = response.body();

using var client = new HttpClient();

var request = new HttpRequestMessage(
    HttpMethod.Post,
    "https://sandbox.sparefinancial.sa/api/v1.0/ais/Transaction/List?accountId=ACCOUNT_ID&consentId=CONSENT_ID");
request.Headers.Add("Authorization", $"Bearer {accessToken}");

var response = await client.SendAsync(request);

var transactions = await response.Content.ReadAsStringAsync();

req, _ := http.NewRequest(
    http.MethodPost,
    "https://sandbox.sparefinancial.sa/api/v1.0/ais/Transaction/List?accountId=ACCOUNT_ID&consentId=CONSENT_ID",
    nil,
)
req.Header.Set("Authorization", "Bearer "+accessToken)

res, err := http.DefaultClient.Do(req)
if err != nil {
    log.Fatal(err)
}
defer res.Body.Close()

transactions, _ := io.ReadAll(res.Body)

Integration summary

Get an account ID

List Accounts and pick the account to query.

Query balance and/or transactions

Call the balance endpoint for the current position, and the transaction endpoint with your filters for history.

Parse the structured response

Read balances by type; iterate transactions using the Transaction Data Object fields.

Roadmap

Transaction categorization (utilities, groceries, etc.) is forthcoming.

Key takeaways

Balances give the point-in-time position by type (available, credit, reserved); transactions give the movement history.
Filter transactions by type (Credit/Debit), status (Pending/Booked/InterimPending), and booking date range.
Both are keyed by account ID from the Accounts endpoint.

Continue learning

Transaction Data Object

Field-by-field transaction shape.

Accounts

List accounts to get an account ID.