Sparados API Integration Guide

1. INTEGRATION MODELS OVERVIEW

Sparados offers three integration models. They differ in who authenticates the end user, who displays the card to the end user, and how much of the user interface you build yourself. Card and balance management, such as creating balances, assigning cards, and setting limits, is always done through the Sparados API in all three models.

SIMPLE API INTEGRATION
You manage cards and balances through the Sparados API as usual. Your end users log in and view their card, transactions and limits through a web or mobile application hosted and authenticated entirely by Sparados. You do not build or host any end-user facing interface.

WIDGET API INTEGRATION
You authenticate end users in your own application. The Sparados Card Widget, embedded in your application as an iframe or WebView, shows the card details along with Add to Apple Wallet and Add to Google Wallet buttons. Balance and transaction history can also be displayed if you want them included. Sensitive card data such as PAN and CVV is never exposed to your backend.

FULL API INTEGRATION
You receive full card data through the Sparados API, including PAN and CVV, and build your own end-user interface entirely. This model gives you full control but also full PCI DSS responsibility. See the Full API Integration section for details.

COMPARISON

Using the Sparados platform, partners can issue virtual and physical cards, manage balances and spending limits, automate expense workflows, and integrate card management directly into their own systems and applications.

The Sparados API supports:

Corporate card issuing
Card lifecycle management
Transaction processing
Budget and spending controls
3DS and OTP authentication flows
Balance and approval management
Server-to-server communication using Mutual TLS
Webhooks and transaction notifications

2. ENVIRONMENT SETUP

Before calling Sparados APIs, your corporation must be configured by Sparados and access to the selected environment must be enabled.

Access to BETA and PROD environments is provided after client verification and signing the cooperation agreement with Sparados.

Server-to-Server Access

Sparados APIs use Mutual TLS authentication for server-to-server communication.

Certificate generation, CSR structure, and environment-specific certificate requirements are described in the dedicated section:

Connecting to Server-to-Server APIs

Once your CSR is signed by Sparados, you can use the issued certificate to authenticate API requests within the selected environment.

API Addresses

API	Integration	BETA	PROD
Cards API	Simple / Full	https://sparadosv2-bc-api.secure-verestro.dev/secure	https://sparadosv2-bc-api.secure-verestro.com/secure
Transaction API	Simple / Full	https://services.upaidtest.pl/thc	https://services.upaid.pl/thc
User, Card Data, 3DS and X-Pay Notifications API	Full	https://sp-api.secure-verestro.dev	https://sp-api.secure-verestro.com

3. REQUIRED CORPORATE PANEL VALUES

Before creating card approvals or managing card issuing workflows through Sparados APIs, you need to collect the required values from the Corporate Panel.

These values may be used in all three integration models, Simple, Widget and Full API Integration, depending on the selected integration model.

Card Visual ID

You can find the visualId during the card assignment process in the Corporate Panel.

To copy the Card Visual ID:

Go to card assignment.
Select the card visual you want to use.
Click the copy icon displayed on the card visual.

The copied value should be used as:

card.visual.id

when creating an approval via API.

Balance ID / Card Alias ID

You can find the Card Alias ID in the Accounts section of the Corporate Panel.

To copy the Card Alias ID:

Go to Accounts.
Select the relevant account.
Click Copy Card Alias ID / Balance ID.

The copied value should be used as:

balance.id

when creating an approval via API.

Important

The balance.id used in Approval API methods is the Card Alias ID copied from the Corporate Panel.

It is different from the balanceId used for balance checking endpoints, such as:

GET /secure/balances/{balanceId}

The balanceId for balance checking is provided by Sparados after a payment account is created for the partner.

4. INTEGRATION DOCUMENTATION LINKS

For detailed technical documentation, please refer to the relevant integration section:

Integration type	Documentation link
Simple API Integration	Simple API Integration
Widget API	Widget API
Full API Integration	Full API Integration

Choose the integration model that matches your implementation scope before starting the technical integration.