Quick Start Setup

Every integration starts with credentials, a webhook endpoint, and authentication. How you register the webhook and how you authenticate depend on the market selected in the sidebar.

Before you start

You will need a Spare sandbox account. If you haven't signed up yet, request access from Spare before continuing.

Create API credentials

Sign in to the Spare Dashboard with your sandbox account.
Open Developer → Developer Tools → Api-keys.
Click Generate new API key.
Provide your own public/private key pair, or click Generate key pairs. Generating a pair downloads the private key to your machine. Store it securely; you need it later to sign write requests where your market requires it.
See Request Signing.
Whitelist the IP addresses that may use this API key. Requests from any other IP are rejected.
Click Create API Key. Spare emails you the App ID and API key. Store both in a secrets manager or .env file.

Keep credentials server-side

Keep your API key and private key off mobile apps and browser code. Authenticate and sign from your backend only.

Approval. When you request an API key, Spare checks your key-count limit and your team structure, then routes the request for approval. Whether approval is needed depends on who is asking:

You are…	Approval	Approved by
The only member (owner)	Not required	Auto-approved
The owner, with admins on the team	Required	An admin
An admin, with an owner on the team	Required	The owner
An admin, with an owner and other admins	Required	The owner or an admin
A non-admin team member	Required	The owner or an admin

Owners and admins get an email to approve or decline. Once approved, the App ID and API key are delivered to the requester by email.

Webhook subscriptions are managed through the API. Once you have an access token, call POST /webhooks with your HTTPS URL, the payments product, and the resource types you want to receive events for. Each delivery is a signed compact JWS; your receiver must return 202 Accepted.

See Webhooks for an overview, and Manage Subscriptions for the full subscription API.

Set environment variables

export SPARE_APP_ID="your-app-id"
export SPARE_API_KEY="your-api-key"
export SPARE_TENANT="your-tenant"

Authenticate

Exchange your credentials for a short-lived access token, then include it on every subsequent request. The endpoint and headers differ by market, set your market with the country selector in the sidebar.

curl -X POST https://api.sandbox.tryspare.ae/auth/api-keys/sessions \
  -H "x-tenant: UAE" \
  -H "app-id: $SPARE_APP_ID" \
  -H "x-api-key: $SPARE_API_KEY"

const res = await fetch(
  "https://api.sandbox.tryspare.ae/auth/api-keys/sessions",
  {
    method: "POST",
    headers: {
      "x-tenant": "UAE",
      "app-id": process.env.SPARE_APP_ID!,
      "x-api-key": process.env.SPARE_API_KEY!,
    },
  },
);

const { accessToken, expiresIn } = await res.json();

import os
import requests

res = requests.post(
    "https://api.sandbox.tryspare.ae/auth/api-keys/sessions",
    headers={
        "x-tenant": "UAE",
        "app-id": os.environ["SPARE_APP_ID"],
        "x-api-key": os.environ["SPARE_API_KEY"],
    },
)

data = res.json()
access_token = data["accessToken"]

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sandbox.tryspare.ae/auth/api-keys/sessions"))
    .header("x-tenant", "UAE")
    .header("app-id", System.getenv("SPARE_APP_ID"))
    .header("x-api-key", System.getenv("SPARE_API_KEY"))
    .POST(HttpRequest.BodyPublishers.noBody())
    .build();

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

// Parse the JSON response and read the accessToken field
JsonNode data = new ObjectMapper().readTree(response.body());
String accessToken = data.get("accessToken").asText();

using System;
using System.Net.Http;
using System.Text.Json;
using System.Threading.Tasks;

using var client = new HttpClient();

var request = new HttpRequestMessage(
    HttpMethod.Post,
    "https://api.sandbox.tryspare.ae/auth/api-keys/sessions");
request.Headers.Add("x-tenant", "UAE");
request.Headers.Add("app-id", Environment.GetEnvironmentVariable("SPARE_APP_ID"));
request.Headers.Add("x-api-key", Environment.GetEnvironmentVariable("SPARE_API_KEY"));

var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();

using var doc = JsonDocument.Parse(body);
var accessToken = doc.RootElement.GetProperty("accessToken").GetString();

package main

import (
	"encoding/json"
	"net/http"
	"os"
)

req, err := http.NewRequest(
	http.MethodPost,
	"https://api.sandbox.tryspare.ae/auth/api-keys/sessions",
	nil,
)
if err != nil {
	panic(err)
}

req.Header.Set("x-tenant", "UAE")
req.Header.Set("app-id", os.Getenv("SPARE_APP_ID"))
req.Header.Set("x-api-key", os.Getenv("SPARE_API_KEY"))

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

var data struct {
	AccessToken string `json:"accessToken"`
	ExpiresIn   int    `json:"expiresIn"`
}
json.NewDecoder(res.Body).Decode(&data)

accessToken := data.AccessToken

Use the returned accessToken on subsequent calls, e.g. discovering providers:

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

Tokens expire, refresh via POST /auth/api-keys/sessions/refresh before they do, or on a 401.

Key takeaways

Every integration needs credentials, a webhook endpoint, and authentication. Webhook setup is API-based in the UAE and dashboard-based in other markets.
The tenant value is a request parameter, not an account-level setting: it determines which regulatory context you're operating in.
Store the App ID, API key, and private key securely on your server. The private key is required to sign write requests where your market requires x-signature.
IP whitelist binds each API key; requests from non-whitelisted IPs are rejected.

Continue learning

Integration Flow

What happens after you have a token: providers and consent.

Webhooks

Event catalog and signature verification.

API Reference

Interactive docs for every endpoint.

Create API credentials

Configure a webhook endpoint

Set environment variables

Authenticate

On this page