Integration Flow

The request sequence every integration follows, authenticate, discover, consent, authorize, access.

Whether you're reading account data, initiating a payment, or running a verification check, every integration follows the same five-step sequence. The concrete request/response shapes differ by use case, this page covers the shape of the flow itself.

Base URL and authentication

The five-step sequence is the same everywhere; the base URL and authentication for your market are below.

Sandbox base URL	Authentication	Integration
`https://api.sandbox.tryspare.ae`	Session token from App ID + API key; send an `x-tenant: UAE` header	REST or TypeScript SDK

The TypeScript SDK is available now; Python, Java, C#, and Go are coming soon (under review). Integrate over REST in the meantime.

Run the UAE API in Postman

Import the full collection and call every endpoint, no code required.

Open in Postman

The five steps

1. Authenticate

Exchange your App ID and API key for a bearer access token. See Quick Start Setup for the request.

2. Discover providers

List the banks and institutions available for your market.

curl "https://api.sandbox.tryspare.ae/providers?countryCode=AE" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-tenant: UAE"

const res = await fetch(
  "https://api.sandbox.tryspare.ae/providers?countryCode=AE",
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "x-tenant": "UAE",
    },
  },
);

const providers = await res.json();

res = requests.get(
    "https://api.sandbox.tryspare.ae/providers",
    params={"countryCode": "AE"},
    headers={
        "Authorization": f"Bearer {access_token}",
        "x-tenant": "UAE",
    },
)

providers = res.json()

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sandbox.tryspare.ae/providers?countryCode=AE"))
    .header("Authorization", "Bearer " + accessToken)
    .header("x-tenant", "UAE")
    .GET()
    .build();

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

String providers = response.body();

using var client = new HttpClient();

var request = new HttpRequestMessage(
    HttpMethod.Get,
    "https://api.sandbox.tryspare.ae/providers?countryCode=AE");
request.Headers.Add("Authorization", $"Bearer {accessToken}");
request.Headers.Add("x-tenant", "UAE");

var response = await client.SendAsync(request);

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

req, _ := http.NewRequest(
    http.MethodGet,
    "https://api.sandbox.tryspare.ae/providers?countryCode=AE",
    nil,
)
req.Header.Set("Authorization", "Bearer "+accessToken)
req.Header.Set("x-tenant", "UAE")

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

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

The response lists each provider's ID and code, you'll reference these when creating a consent. See the API Reference for the full request and response schema.

A consent is the customer's authorization for Spare to act on their behalf. What the consent is for depends on your use case:

Reading account data → a data-access consent
Initiating a payment → a payment consent linked to a payment request
Running a verification check → a verification consent

Every consent, regardless of type, returns an authorizationUrl.

4. Customer authorization

Redirect the customer to the authorizationUrl. They authenticate with their bank and approve the specific access or action you requested. Spare receives the callback and updates the consent status.

5. Access the result

Once the consent is authorized, call the endpoint for your use case, fetch account data, check payment status, or retrieve verification results. Use webhooks to know the moment status changes, instead of polling.

Pick your concrete flow

This page describes the shape of the sequence. For the exact request bodies and response fields for your use case, see the Guides section or your market's availability under Coverage.

Key takeaways

Every integration is: authenticate → discover providers → create a consent → customer authorizes → access the result.
A consent's purpose (data access, payment, verification) depends on your use case, not on the platform mechanics.
Prefer webhooks over polling once you're past initial development.

Continue learning

Data Types

Field formats used across every response.

Error Codes

How failures are reported.

Guides

Concrete, copy-paste flows per use case.