# 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**

<div dir="ltr" id="bkmrk-feature-simple-api-w"><div><table style="width: 78.809524%; height: 383px;"><thead><tr style="height: 45px;"><th scope="col" style="width: 33.289275%; height: 45px;">Feature</th><th scope="col" style="width: 13.276529%; height: 45px;">Simple API</th><th scope="col" style="width: 36.305702%; height: 45px;">Widget API</th><th scope="col" style="width: 17.008119%; height: 45px;">Full API</th></tr></thead><tbody><tr style="height: 29px;"><td style="width: 33.289275%; height: 29px;">Fast integration</td><td style="width: 13.276529%; height: 29px;">1–2 weeks</td><td style="width: 36.305702%; height: 29px;">2-3 weeks</td><td style="width: 17.008119%; height: 29px;">~1 month</td></tr><tr style="height: 29px;"><td style="width: 33.289275%; height: 29px;">Use Sparados mobile/web app</td><td style="width: 13.276529%; height: 29px;">Yes</td><td style="width: 36.305702%; height: 29px;">No</td><td style="width: 17.008119%; height: 29px;">No</td></tr><tr style="height: 45px;"><td style="width: 33.289275%; height: 45px;">Dedicated branded web app</td><td style="width: 13.276529%; height: 45px;">Optional</td><td style="width: 36.305702%; height: 45px;">N/A, widget embedded in your app</td><td style="width: 17.008119%; height: 45px;">No</td></tr><tr style="height: 29px;"><td style="width: 33.289275%; height: 29px;">Create users via API</td><td style="width: 13.276529%; height: 29px;">No</td><td style="width: 36.305702%; height: 29px;">Yes</td><td style="width: 17.008119%; height: 29px;">Yes</td></tr><tr style="height: 29px;"><td style="width: 33.289275%; height: 29px;">Create cards via API</td><td style="width: 13.276529%; height: 29px;">Yes</td><td style="width: 36.305702%; height: 29px;">Yes</td><td style="width: 17.008119%; height: 29px;">Yes</td></tr><tr style="height: 29px;"><td style="width: 33.289275%; height: 29px;">Receive PAN / CVV</td><td style="width: 13.276529%; height: 29px;">No</td><td style="width: 36.305702%; height: 29px;">No</td><td style="width: 17.008119%; height: 29px;">Yes</td></tr><tr style="height: 45px;"><td style="width: 33.289275%; height: 45px;">Add to Apple/Google Wallet</td><td style="width: 13.276529%; height: 45px;">Yes</td><td style="width: 36.305702%; height: 45px;">Yes, via widget buttons</td><td style="width: 17.008119%; height: 45px;">You implement</td></tr><tr style="height: 45px;"><td style="width: 33.289275%; height: 45px;">Balance and transaction history</td><td style="width: 13.276529%; height: 45px;">Included</td><td style="width: 36.305702%; height: 45px;">Optional, configurable</td><td style="width: 17.008119%; height: 45px;">You implement</td></tr><tr style="height: 29px;"><td style="width: 33.289275%; height: 29px;">PCI DSS scope</td><td style="width: 13.276529%; height: 29px;">No</td><td style="width: 36.305702%; height: 29px;">Minimal</td><td style="width: 17.008119%; height: 29px;">Yes</td></tr></tbody></table>

</div></div>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  
Apple Wallet and Google Wallet passes (SmartPass), see [SmartPass API Integration](https://developer.sparados.com/books/sparados-api-documentation/page/smartpass-api-integration)

##### <span class="s1">**2. ENVIRONMENT SETUP**</span>

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**

<table border="1" cellpadding="8" cellspacing="0" id="bkmrk-api-integration-beta" width="100%"><thead><tr><th>**API**

</th><th>**Integration**

</th><th>**BETA**

</th><th>**PROD**

</th></tr></thead><tbody><tr><td>Cards API

</td><td>Simple / Full

</td><td>`https://sparadosv2-bc-api.secure-verestro.dev/secure`

</td><td>`https://sparadosv2-bc-api.secure-verestro.com/secure`

</td></tr><tr><td>Transaction API

</td><td>Simple / Full

</td><td>`https://services.upaidtest.pl/thc`

</td><td>`https://services.upaid.pl/thc`

</td></tr><tr><td>User, Card Data, 3DS and X-Pay Notifications API

</td><td>Full

</td><td>`https://sp-api.secure-verestro.dev`

</td><td>`https://sp-api.secure-verestro.com`

</td></tr></tbody></table>

##### <span class="s1">**3. REQUIRED CORPORATE PANEL VALUES**</span>

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 <span class="s1">**Accounts**</span> section of the Corporate Panel.

To copy the Card Alias ID:

Go to <span class="s1">**Accounts**</span>.  
Select the relevant account.  
Click <span class="s1">**Copy Card Alias ID / Balance ID**</span>.

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.

##### <span class="s1">**4. INTEGRATION DOCUMENTATION LINKS**</span>

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

<table border="1" cellpadding="8" cellspacing="0" id="bkmrk-integration-type-doc" width="100%"><thead><tr><th>**Integration type**

</th><th>**Documentation link**

</th></tr></thead><tbody><tr><td>Simple API Integration

</td><td>[Simple API Integration](https://developer.sparados.com/books/sparados-api-documentation/page/simple-api-integration)</td></tr><tr><td>Widget API

</td><td>[Widget API](https://developer.sparados.com/books/sparados-api-documentation/page/widget-api-integration)</td></tr><tr><td>Full API Integration

</td><td>[Full API Integration](https://developer.sparados.com/books/sparados-api-documentation/page/full-api-integration)</td></tr><tr><td>SmartPass API (Apple Wallet and Google Wallet passes)

</td><td>[SmartPass API Integration](https://developer.sparados.com/books/sparados-api-documentation/page/smartpass-api-integration)</td></tr></tbody></table>

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