# Sparados API Documentation

Technical documentation for integrating with Sparados corporate card issuing, expense management and transaction processing platform.

# Connecting to server-to-server APIs

### Environments

We have two environments available for our partners.

- Beta - This is environment you're going to use during integration with our services.
- Production - This is live environment.

### Authorization

Our APIs are secured with Mutual TLS Authentication. You will need certificate signed by us in order to connect. To get a certificate please send us an Certificate Signing Request (CSR). We will sign it and return a valid certificate in a response.

CSR should have following structure:

#### For Beta/Production

You will need separate certificates for Beta and Production environments, however they can be generated in exactly the same way.

<table id="bkmrk-field-example-value--0" style="width: 84.938272%;"><thead><tr><th style="width: 26.346434%;">Field</th><th style="width: 73.653566%;">Example value</th></tr></thead><tbody><tr><td style="width: 26.346434%;">Common Name (CN)</td><td style="width: 73.653566%;">`V-Sparados`

</td></tr><tr><td style="width: 26.346434%;">Organization (O)</td><td style="width: 73.653566%;">Name of your company  
</td></tr><tr><td style="width: 26.346434%;">Organizational Unit (OU)</td><td style="width: 73.653566%;">\[UUID\] corp\_id sent by Sparados admin</td></tr><tr><td style="width: 26.346434%;">Locality (L)</td><td style="width: 73.653566%;">City where your organization is located</td></tr><tr><td style="width: 26.346434%;">State/County/Region (ST)</td><td style="width: 73.653566%;">State/County where your organization is located  
</td></tr><tr><td style="width: 26.346434%;">Country (C)</td><td style="width: 73.653566%;">Two-letter country code where organization is located (ISO 3166-1 alpha-2)  
</td></tr><tr><td style="width: 26.346434%;">Email Address</td><td style="width: 73.653566%;">Email to be contacted in case of forced renewal  
</td></tr></tbody></table>

##### Example CSR generation command for Beta and Production

<p class="callout info">**Remember to replace parameters and file names with your own data** Commas cannot be used in parameters  
Minimum key length is RSA 2048</p>

```shell
openssl req -new -newkey rsa:4096 -keyout companyName.key -out companyName.csr -nodes -subj '/C=US/ST=Florida/L=Miami/O=SomeCompany/OU=UUID/CN=V-Sparados/emailAddress=example@user.com'
```

---

# Sparados API Integration Guide

##### <span class="s1">**1. INTRODUCTION**</span>

Sparados provides APIs and hosted applications for corporate card issuing, expense management, and transaction processing.

The platform supports two integration models:

**Simple API Integration** — fast implementation using Sparados hosted mobile and web applications.

**Full API Integration** — embedded card issuing with full control over users, cards, card data, and authentication flows.

**Choose Integration Type**

<table border="1" cellpadding="8" cellspacing="0" id="bkmrk-feature-simple-api-f" width="100%"><thead><tr><th>**Feature**

</th><th>**Simple API**

</th><th>**Full API**

</th></tr></thead><tbody><tr><td>Fast integration

</td><td>1–2 days

</td><td>~1 month

</td></tr><tr><td>Use Sparados mobile app

</td><td>Yes

</td><td>No

</td></tr><tr><td>Use Sparados web app

</td><td>Yes

</td><td>No

</td></tr><tr><td>Dedicated branded web app

</td><td>Optional

</td><td>No

</td></tr><tr><td>Dedicated branded OTP SMS / WhatsApp / Email

</td><td>Optional

</td><td>No

</td></tr><tr><td>Create users via API

</td><td>No

</td><td>Yes

</td></tr><tr><td>Create cards via API

</td><td>Yes

</td><td>Yes

</td></tr><tr><td>Receive PAN / CVV

</td><td>No

</td><td>Yes

</td></tr><tr><td>Receive OTP / 3DS

</td><td>No

</td><td>Yes

</td></tr><tr><td>Apple Pay / Google Pay OTP

</td><td>No

</td><td>Yes

</td></tr><tr><td>PCI DSS scope

</td><td>No

</td><td>Yes

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

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

Before calling Sparados APIs, your corporation must be configured by Sparados and Mutual TLS authentication must be enabled for your environment.

##### <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 both Simple API Integration 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>Full API Integration

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

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

# Simple API Integration

#### Simple API Integration

Simple API Integration is the fastest way to start issuing cards with Sparados.

In this model, the partner uses Sparados APIs to create card approvals and receive transaction history, while Sparados hosted web or mobile applications are used for user registration, card access, and authentication flows.

Simple API Integration is recommended for partners who want to launch quickly and use Sparados hosted end-user experience instead of building the full cardholder flow on their own.

Simple API Integration uses two main APIs:

<div class="TyagGW_tableContainer" id="bkmrk-api-purpose-approval"><div class="group TyagGW_tableWrapper flex flex-col-reverse w-fit" tabindex="-1"><table class="w-fit min-w-(--thread-content-width)" data-end="636" data-start="393" style="width: 100%; height: 121.16848px;"><thead data-end="410" data-start="393"><tr data-end="410" data-start="393" style="height: 29.375px;"><th class="" data-col-size="sm" data-end="399" data-start="393" style="width: 18.685301%; height: 29.375px;">API</th><th class="" data-col-size="lg" data-end="410" data-start="399" style="width: 81.212798%; height: 29.375px;">Purpose</th></tr></thead><tbody data-end="636" data-start="421"><tr data-end="552" data-start="421" style="height: 45.89674px;"><td data-col-size="sm" data-end="436" data-start="421" style="width: 18.685301%; height: 45.89674px;">Approval API</td><td data-col-size="lg" data-end="552" data-start="436" style="width: 81.212798%; height: 45.89674px;">Used to create card approvals, assign cards to users, and define budgets, validity periods, and spending limits.</td></tr><tr data-end="636" data-start="553" style="height: 45.89674px;"><td data-col-size="sm" data-end="579" data-start="553" style="width: 18.685301%; height: 45.89674px;">Transaction History API</td><td data-col-size="lg" data-end="636" data-start="579" style="width: 81.212798%; height: 45.89674px;">Used to receive and process card transaction history.</td></tr></tbody></table>

</div></div>##### **1. How Simple API Integration Works**

In the Simple API model, the partner starts by creating an approval for the end user using the Approval API.

The approval contains card assignment details, including the user’s email address and phone number. Optionally, the partner may also provide additional user details such as first name, last name, date of birth, and nationality.

After the approval is created, the end user receives an email with a registration link. Depending on the configured setup, the link directs the user to a Sparados hosted mobile or web application.

In the web application flow, the registration link may already contain the user data previously provided through the API.

The end user completes the registration process by:

- confirming their data
- accepting Terms and Conditions
- setting a PIN for the application
- verifying their phone number

After registration is completed, Sparados matches the user with the previously created approval using the email address and phone number.

If the data matches, the card is generated and assigned to the user automatically.

If the data does not match, the user can use the 6-digit code received in the registration email to complete the matching process.

Once the card is generated and assigned, the approval status changes from `ACCEPTED` to `DELIVERED`.

**Simple API Flow Diagram**

**<span style="color: #000000;">[![postApproval.png](https://developer.sparados.com/uploads/images/gallery/2026-05/scaled-1680-/postapproval.png)](https://developer.sparados.com/uploads/images/gallery/2026-05/postapproval.png)</span>**

##### **2. Values used in Sparados Cards API**

**Swagger documentation is in the end of document**

This section describes common value formats used across Sparados Cards API.  
These rules apply when creating approvals, defining card limits, setting validity periods, and managing card-related operations.

<span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Date format</span>

Sparados APIs use the ISO 8601 date and time format.

The expected format is:

```
YYYY-MM-DDTHH:mm:ss.SSSZ
```

<div class="relative w-full mt-4 mb-1" id="bkmrk--1"><div class=""><div class="relative"><div class="h-full min-h-0 min-w-0"><div class="h-full min-h-0 min-w-0"><div class="border border-token-border-light border-radius-3xl corner-superellipse/1.1 rounded-3xl"><div class="h-full w-full border-radius-3xl bg-token-bg-elevated-secondary corner-superellipse/1.1 overflow-clip rounded-3xl lxnfua_clipPathFallback"><div class="relative"><div class="pe-11 pt-3"><div class="relative z-0 flex max-w-full"><div class="q9tKkq_viewer cm-editor z-10 light:cm-light dark:cm-light flex h-full w-full flex-col items-stretch ͼs ͼ16" dir="ltr" id="bkmrk--2"><div class="cm-scroller">  
</div></div></div></div></div></div></div></div></div></div></div></div>Where:

- `T` separates the date from the time
- `Z` represents Zulu time / UTC time

Example:

```
2023-05-22T10:00:01.953Z
```

<span style="color: rgb(0, 0, 0); font-family: Arial, sans-serif; font-size: 11pt; font-style: normal; font-variant-caps: normal; font-weight: bold; white-space-collapse: preserve;">Minor values</span>

All numeric amount values used in Sparados Cards API are provided in minor units.  
For example, to assign a card with a limit of `100.50 EUR`, send:

```
10050
```

This applies to values such as:

- card budget
- additional limits
- budget increases
- budget decreases

<span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Currency</span>

Card approvals are created in the currency of the account / balance. The currency does not need to be provided separately when creating an approval, because it is inherited from the selected account / balance.  
Each account can have only one currency. Transactions may still be performed in other currencies, depending on the card configuration and transaction rules.

##### **3. Creating Card Approvals**

To assign a card to a corporation member, use the `POST /secure/approvals` endpoint.

A card approval defines who should receive the card, what budget can be used, how long the card should be valid, and what transaction limits should apply. After the approval is created, Sparados sends a registration email to the end user. When the user completes registration and the data matches the approval, the card is generated and assigned automatically. Remember to save the returned `approvalId` on your side. It will be required later when editing the approval, locking or unlocking the card, changing limits, increasing or decreasing the available budget, or unassigning the card.

**Request Body Fields**

**Required and Optional Fields**  
Required fields are marked with `*`.

<table id="bkmrk-field-required-descr" style="width: 99.999993%; height: 998.72284px;"><thead><tr style="height: 29.375px;"><th style="width: 16.80338%; height: 29.375px;">Field</th><th align="right" style="width: 11.082329%; height: 29.375px;">Required</th><th style="width: 72.100362%; height: 29.375px;">Description</th></tr></thead><tbody><tr style="height: 45.89674px;"><td style="width: 16.80338%; height: 45.89674px;">`balance.id`</td><td align="right" style="width: 11.082329%; height: 45.89674px;">Yes</td><td style="width: 72.100362%; height: 45.89674px;">Balance ID / Card Alias ID assigned to your corporation. This value can be copied from the Corporate Panel.</td></tr><tr style="height: 45.89674px;"><td style="width: 16.80338%; height: 45.89674px;">`user.id`</td><td align="right" style="width: 11.082329%; height: 45.89674px;">Conditional</td><td style="width: 72.100362%; height: 45.89674px;">Required if you assign the card to an existing user. If `user.id` is provided, user contact details such as `email`, `prefix`, and `phone` are not required.</td></tr><tr style="height: 45.89674px;"><td style="width: 16.80338%; height: 45.89674px;">`user.email`</td><td align="right" style="width: 11.082329%; height: 45.89674px;">Conditional</td><td style="width: 72.100362%; height: 45.89674px;">Required if `user.id` is not provided. Used for registration, communication, and matching the user with the approval.</td></tr><tr style="height: 29.375px;"><td style="width: 16.80338%; height: 29.375px;">`user.prefix`</td><td align="right" style="width: 11.082329%; height: 29.375px;">Conditional</td><td style="width: 72.100362%; height: 29.375px;">Required if `user.id` is not provided. Phone number prefix without `+`. Example: `48`.</td></tr><tr style="height: 45.89674px;"><td style="width: 16.80338%; height: 45.89674px;">`user.phone`</td><td align="right" style="width: 11.082329%; height: 45.89674px;">Conditional</td><td style="width: 72.100362%; height: 45.89674px;">Required if `user.id` is not provided. User phone number used for authorization and matching.</td></tr><tr style="height: 29.375px;"><td style="width: 16.80338%; height: 29.375px;">`user.firstName`</td><td align="right" style="width: 11.082329%; height: 29.375px;">No</td><td style="width: 72.100362%; height: 29.375px;">User first name. Can be provided when creating approval for a new user / registration flow.</td></tr><tr style="height: 29.375px;"><td style="width: 16.80338%; height: 29.375px;">`user.lastName`</td><td align="right" style="width: 11.082329%; height: 29.375px;">No</td><td style="width: 72.100362%; height: 29.375px;">User last name. Can be provided when creating approval for a new user / registration flow.</td></tr><tr style="height: 29.375px;"><td style="width: 16.80338%; height: 29.375px;">`user.birthDate`</td><td align="right" style="width: 11.082329%; height: 29.375px;">No</td><td style="width: 72.100362%; height: 29.375px;">User date of birth in date-time format. Example: `1980-01-01T00:00:00.000+00:00`.</td></tr><tr style="height: 29.375px;"><td style="width: 16.80338%; height: 29.375px;">`user.nationality`</td><td align="right" style="width: 11.082329%; height: 29.375px;">No</td><td style="width: 72.100362%; height: 29.375px;">User nationality in ISO country code format. Example: `PL`.</td></tr><tr style="height: 45.89674px;"><td style="width: 16.80338%; height: 45.89674px;">`rules.budgetMinor`</td><td align="right" style="width: 11.082329%; height: 45.89674px;">Yes</td><td style="width: 72.100362%; height: 45.89674px;">Total amount in minor units that the user can spend using the card. The amount is provided in the currency of the selected balance.</td></tr><tr style="height: 45.89674px;"><td style="width: 16.80338%; height: 45.89674px;">`rules.validityPeriod.startDate`</td><td align="right" style="width: 11.082329%; height: 45.89674px;">Yes</td><td style="width: 72.100362%; height: 45.89674px;">Start date and time of the card validity period in ISO 8601 format.</td></tr><tr style="height: 45.89674px;"><td style="width: 16.80338%; height: 45.89674px;">`rules.validityPeriod.endDate`</td><td align="right" style="width: 11.082329%; height: 45.89674px;">Yes</td><td style="width: 72.100362%; height: 45.89674px;">End date and time of the card validity period in ISO 8601 format.</td></tr><tr style="height: 45.89674px;"><td style="width: 16.80338%; height: 45.89674px;">`rules.validityPeriod.timezone`</td><td align="right" style="width: 11.082329%; height: 45.89674px;">Yes</td><td style="width: 72.100362%; height: 45.89674px;">Timezone used to adjust the card validity period to the exact local time. Example: `Europe/Warsaw`.</td></tr><tr style="height: 29.375px;"><td style="width: 16.80338%; height: 29.375px;">`rules.limits`</td><td align="right" style="width: 11.082329%; height: 29.375px;">No</td><td style="width: 72.100362%; height: 29.375px;">List of additional card limits.</td></tr><tr style="height: 45.89674px;"><td style="width: 16.80338%; height: 45.89674px;">`rules.limits.amountMinor`</td><td align="right" style="width: 11.082329%; height: 45.89674px;">Conditional</td><td style="width: 72.100362%; height: 45.89674px;">Required when a limit object is provided. Additional periodic limit amount in minor units. For MCC-based rules, this value may be set to `0`.</td></tr><tr style="height: 45.89674px;"><td style="width: 16.80338%; height: 45.89674px;">`rules.limits.timeUnit`</td><td align="right" style="width: 11.082329%; height: 45.89674px;">Conditional</td><td style="width: 72.100362%; height: 45.89674px;">Required when a limit object is provided. Period for the additional limit. Available values: `daily`, `weekly`, `monthly`.</td></tr><tr style="height: 45.89674px;"><td style="width: 16.80338%; height: 45.89674px;">`rules.limits.type`</td><td align="right" style="width: 11.082329%; height: 45.89674px;">Conditional</td><td style="width: 72.100362%; height: 45.89674px;">Required when a limit object is provided. Available values include `general`, `ecommerce`, `atm`, `foreign_amount`, `mcc_whitelist`, `mcc_blacklist`.</td></tr><tr style="height: 45.89674px;"><td style="width: 16.80338%; height: 45.89674px;">`rules.limits.mccList`</td><td align="right" style="width: 11.082329%; height: 45.89674px;">Conditional</td><td style="width: 72.100362%; height: 45.89674px;">Required for MCC-based rules such as `mcc_whitelist` and `mcc_blacklist`. Contains the list of MCC codes used by the rule. MCC values may be provided as strings, e.g. `"5812"`.</td></tr><tr style="height: 45.89674px;"><td style="width: 16.80338%; height: 45.89674px;">`rules.purpose.ecommerce`</td><td align="right" style="width: 11.082329%; height: 45.89674px;">Yes</td><td style="width: 72.100362%; height: 45.89674px;">Defines whether the card can be used for e-commerce transactions. Currently, this should be set to `true`.</td></tr><tr style="height: 45.89674px;"><td style="width: 16.80338%; height: 45.89674px;">`rules.purpose.allowChangeRequest`</td><td align="right" style="width: 11.082329%; height: 45.89674px;">No</td><td style="width: 72.100362%; height: 45.89674px;">Defines whether the user can request changes to card limits. `true` means the user can send a change request. `false` means change requests are disabled.</td></tr><tr style="height: 45.89674px;"><td style="width: 16.80338%; height: 45.89674px;">`card.description`</td><td align="right" style="width: 11.082329%; height: 45.89674px;">No</td><td style="width: 72.100362%; height: 45.89674px;">Description displayed on the card visual in the user application. Can be a text value, e.g. `Travel only`, or `null`.</td></tr><tr style="height: 45.89674px;"><td style="width: 16.80338%; height: 45.89674px;">`card.visual.id`</td><td align="right" style="width: 11.082329%; height: 45.89674px;">No</td><td style="width: 72.100362%; height: 45.89674px;">ID of the card visual. This value can be copied from the Corporate Panel. If not provided, the default Sparados visual may be used.</td></tr><tr style="height: 29.375px;"><td style="width: 16.80338%; height: 29.375px;">`tags`</td><td align="right" style="width: 11.082329%; height: 29.375px;">No</td><td style="width: 72.100362%; height: 29.375px;">List of tag IDs or tag values assigned to the approval. Can be an empty array.</td></tr><tr style="height: 29.375px;"><td style="width: 16.80338%; height: 29.375px;">`assignedTags.id`</td><td align="right" style="width: 11.082329%; height: 29.375px;">No</td><td style="width: 72.100362%; height: 29.375px;">ID of an existing assigned tag. Used only if your configuration supports assigned tag objects.</td></tr></tbody></table>

<div align="left" dir="ltr" id="bkmrk-rules.budgetminor-%2A-" style="margin-left: 0pt;"></div>OTP SMS Code Verification (BETA)

In the BETA environment, OTP SMS codes used during user registration and manual card assignment can be checked using the endpoint below:

```
GET https://kolombo.verestro.dev/api/projects/Sparados/sms/{phoneNumber}/history/latest
```

<div class="relative w-full mt-4 mb-1" id="bkmrk--3"></div>Example:

```
https://kolombo.verestro.dev/api/projects/Sparados/sms/48728209827/history/latest
```

`phoneNumber` should contain country prefix without `+` and without spaces.

<span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Additional limits</span>

<span style="color: #000000;">It's possible to set additional limits on the card, which are optional. If left null, the card issuing service will set default values.</span>

**<span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-style: normal; font-variant: normal; white-space-collapse: preserve;">There are four types of additional limits:</span>**

<span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">1. </span><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">General limit </span><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">- periodic limit on all kinds of transactions. This value should be greater than remaining additional limits because it affects them. E.g. if the ATM limit is set to 100 EUR and the general limit is set to 50 EUR, the end user will be able to withdraw only 50 EUR from the ATM. </span><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; text-decoration-line: underline; text-decoration-skip-ink: none; white-space-collapse: preserve;">Possible values:</span><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;"> amount in minor or null.</span>

<span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">2. </span><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Online payment limit</span><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;"> - periodic limit on e-commerce payments. </span><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; text-decoration-line: underline; text-decoration-skip-ink: none; white-space-collapse: preserve;">Possible values</span><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">: 0, amount in minor or null.</span>

<span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">3. </span><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">ATM limit</span><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;"> - periodic limit on ATM withdrawals. </span><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; text-decoration-line: underline; text-decoration-skip-ink: none; white-space-collapse: preserve;">Possible values</span><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">: 0, amount in minor or null.</span>

<span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">4. </span><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Foreign transaction limit</span><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;"> - periodic limit on transactions in a different currency from account currency. Limit is given in the currency of balance and it will be recalculated taking into account exchange rates and commission. </span><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; text-decoration-line: underline; text-decoration-skip-ink: none; white-space-collapse: preserve;">Possible values</span><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">: 0, amount in minor or null.</span>

<span style="color: #000000;">Possible time units for all additional limits are daily, weekly, and monthly</span>

<span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Possible values od the additional limits:</span>

<span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">0 - disabled. End user won't be able to perform online payments, withdraw from ATM or transactions in foreign currencies.</span>

<span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">**Value in minor** - limited to requested value</span>

<span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">**Null** - unlimited. End user will be able to perform online payments, withdraw from ATM or transactions in foreign currencies.</span>

#### <span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Difference between approval and reapproval:</span>

<span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Approval</span><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;"> is created by the corporation in the process of assigning a card. We don't name it simply a card because a card is generated when the end-user redeems a card and the start date of approval occurs. Approval is created earlier, right after calling endpoint </span><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">PUT /secure/approvals/</span><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">.</span>

<span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Reapproval</span><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;"> can be created by the corporation while editing data on approval (using method </span><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">PUT /secure/approvals/{id}</span><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">) in status Delivered or by mobile user when they request a higher limit or change of validity end date. Requesting changes can be disabled by putting the value false in purpose.allowChangeRequest field while creating an approval.</span>

<span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Ensure that you provide all the required fields and follow the instructions to successfully assign a card with the specified limits and rules.</span>

##### **4. Approval Statuses and Available Actions:**

**<span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Statuses of approvals:</span>**

<div align="left" dir="ltr" id="bkmrk-created-occur-only-w" style="margin-left: 0pt;"><table style="border-width: initial; border-style: none; width: 98.7654%;"><colgroup><col style="width: 22.3048%;" width="120"></col><col style="width: 77.6952%;" width="418"></col></colgroup><tbody><tr style="height: 53.5pt;"><td style="vertical-align: top; padding: 5pt 5pt 5pt 5pt; overflow: hidden; overflow-wrap: break-word;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">CREATED</span>

</td><td style="vertical-align: top; padding: 5pt 5pt 5pt 5pt; overflow: hidden; overflow-wrap: break-word;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Occur only when mobile user request changes on reapproval.</span>

</td></tr><tr style="height: 70pt;"><td style="vertical-align: top; padding: 5pt 5pt 5pt 5pt; overflow: hidden; overflow-wrap: break-word;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">ACCEPTED</span>

</td><td style="vertical-align: top; padding: 5pt 5pt 5pt 5pt; overflow: hidden; overflow-wrap: break-word;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">When an Approval is created. </span><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">It changes to DELIVERED status after registration is complete and card is redeemed by end-user.</span>

</td></tr><tr style="height: 53.5pt;"><td style="vertical-align: top; padding: 5pt 5pt 5pt 5pt; overflow: hidden; overflow-wrap: break-word;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">CANCELED</span>

</td><td style="vertical-align: top; padding: 5pt 5pt 5pt 5pt; overflow: hidden; overflow-wrap: break-word;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">When an Approval or Reapproval with status CREATED, ACCEPTED or PREPARED is cancelled by corporation.</span>

</td></tr><tr style="height: 38.5pt;"><td style="vertical-align: top; padding: 5pt 5pt 5pt 5pt; overflow: hidden; overflow-wrap: break-word;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">REJECTED</span>

</td><td style="vertical-align: top; padding: 5pt 5pt 5pt 5pt; overflow: hidden; overflow-wrap: break-word;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">When a Reapproval with status CREATED is rejected by corporation.</span>

</td></tr><tr style="height: 70pt;"><td style="vertical-align: top; padding: 5pt 5pt 5pt 5pt; overflow: hidden; overflow-wrap: break-word;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">EXPIRED</span>

</td><td style="vertical-align: top; padding: 5pt 5pt 5pt 5pt; overflow: hidden; overflow-wrap: break-word;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">When a Reapproval with the status CREATED is not accepted/rejected or status of Approval is ACCEPTED but the card has not been redeemed by mobile user within the given Approval time (until the end of the ValidTo date).</span>

</td></tr><tr style="height: 53.5pt;"><td style="vertical-align: top; padding: 5pt 5pt 5pt 5pt; overflow: hidden; overflow-wrap: break-word;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">PREPARED</span>

</td><td style="vertical-align: top; padding: 5pt 5pt 5pt 5pt; overflow: hidden; overflow-wrap: break-word;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">When approval has been ACCEPTED, redeemed by the end-user and is waiting for card generation. Card is generated on startDate of Approval.</span>

</td></tr><tr style="height: 53.5pt;"><td style="vertical-align: top; padding: 5pt 5pt 5pt 5pt; overflow: hidden; overflow-wrap: break-word;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">DELIVERED</span>

</td><td style="vertical-align: top; padding: 5pt 5pt 5pt 5pt; overflow: hidden; overflow-wrap: break-word;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">When mobile user redeemed card. This is the state of approval in which transactions can be made with a card.</span>

</td></tr><tr style="height: 38.5pt;"><td style="vertical-align: top; padding: 5pt 5pt 5pt 5pt; overflow: hidden; overflow-wrap: break-word;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">FINISHED</span>

</td><td style="vertical-align: top; padding: 5pt 5pt 5pt 5pt; overflow: hidden; overflow-wrap: break-word;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">When an Approval with status DELIVERED exceeds the end date of assignment.</span>

</td></tr><tr style="height: 38.5pt;"><td style="vertical-align: top; padding: 5pt 5pt 5pt 5pt; overflow: hidden; overflow-wrap: break-word;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">REAPPROVED</span>

</td><td style="vertical-align: top; padding: 5pt 5pt 5pt 5pt; overflow: hidden; overflow-wrap: break-word;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">When a reapproval is created for a given Approval that is in Accepted/Delivered status.</span>

</td></tr><tr style="height: 70pt;"><td style="vertical-align: top; padding: 5pt 5pt 5pt 5pt; overflow: hidden; overflow-wrap: break-word;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">LOCKED</span>

</td><td style="vertical-align: top; padding: 5pt 5pt 5pt 5pt; overflow: hidden; overflow-wrap: break-word;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">This is a status of a </span><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">card (not an approval)</span><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;"> but we display it on the diagram below to show that Delivered is the only state of a approval on which we have action to lock and unlock card. </span>

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

</div><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Statuses of an Approval:</span>

<span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;"> </span>

<span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;"><span style="border-width: initial; border-style: none; display: inline-block; overflow: hidden; width: 367px; height: 184px;">[![image-1686858492185.png](https://developer.sparados.com/uploads/images/gallery/2026-05/scaled-1680-/image-1686858492185.png)](https://developer.sparados.com/uploads/images/gallery/2026-05/image-1686858492185.png)</span></span>

<span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Statuses of a Reapproval:</span>

<span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;"><span style="border-width: initial; border-style: none; display: inline-block; overflow: hidden; width: 367px; height: 176px;">[![image-1686858497780.png](https://developer.sparados.com/uploads/images/gallery/2026-05/scaled-1680-/image-1686858497780.png)](https://developer.sparados.com/uploads/images/gallery/2026-05/image-1686858497780.png)![image-1686858497780.png](https://lh6.googleusercontent.com/kaU_AL-130eWb5Jjl6ZzAW3-gSGk_7DRp7kzjj5lLlQXpsMER-gyVD-8z8KCt3YQrMOYXlIH_8hQ_7Qpds5htuKJ9wni3eXe3HUd5ExSF-RdffyxuGIzhg3LQvnrwU2pKWxtAbXqNskpfe9u4-S-040)</span></span>

**<span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Actions available on approvals:</span>**

- <span style="font-size: 11pt; font-family: Arial, sans-serif; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; text-wrap: wrap; color: #000000;">Created: Accept, Reject, Edit, Cancel. </span>
- <span style="font-size: 11pt; font-family: Arial, sans-serif; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; text-wrap: wrap; color: #000000;">Accepted: Cancel</span>
- <span style="font-size: 11pt; font-family: Arial, sans-serif; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; text-wrap: wrap; color: #000000;">Preprared: Cancel</span>
- <span style="font-size: 11pt; font-family: Arial, sans-serif; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; text-wrap: wrap; color: #000000;">Delivered: Lock, Unassign, Edit</span>
- <span style="font-size: 11pt; font-family: Arial, sans-serif; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; text-wrap: wrap; color: #000000;">Locked: Unlock</span>
- <span style="font-size: 11pt; font-family: Arial, sans-serif; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; text-wrap: wrap; color: #000000;">Rejected: —</span>
- <span style="font-size: 11pt; font-family: Arial, sans-serif; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; text-wrap: wrap; color: #000000;">Expired: — </span>
- <span style="font-size: 11pt; font-family: Arial, sans-serif; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; text-wrap: wrap; color: #000000;">Finished: — </span>

**Important! Reapproval Acceptance:**

- <span style="color: #000000;">When a reapproval is accepted, its status changes to "Delivered."</span>
- <span style="color: #000000;">The accepted reapproval replaces the previous approval. Therefore, it's crucial to save the ID of the accepted reapproval because, from that moment, it becomes the valid ID of this approval.</span>
- <span style="color: #000000;">Concurrently, the status of the original approval changes to "Reapproved."</span>

**Unassign card from enduser**

<span style="color: #000000;">If the user has already redeemed the card (status of approval is Delivered), use the **PUT /secure/approvals/{id}/unassign** method to take away the card from the end-user.</span>

<span style="color: #000000;">If the user hasn't redeemed the card yet (status of approval is Accepted or Prepared), use the **PUT /secure/approvals/{id}/cancel** method to take away the card</span>.

#### <span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Increase or decrease available limit on a card</span>

<span style="color: #000000;">To quickly increase the available limit on a card, use the PUT /secure/approvals/{id}/increase\_budget method.</span>

<span style="color: #000000;">To add another 10 EUR to the available limit, put the value: "additionalBudgetMinor": 1000 (assuming the minor currency is used with 1 EUR = 100 minor).</span>

<span style="color: #000000;">To quickly decrease the available limit on a card, use the same method PUT /secure/approvals/{id}/increase\_budget but with a negative value.</span>

<span style="color: #000000;">To subtract 10 EUR from the available limit, put the value: "additionalBudgetMinor": -1000.</span>

##### **4. System Email Notifications**

<span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">E-mails can be adjusted to your corporation and sent in different language. Contact Sparados for details.</span>

<div align="left" dir="ltr" id="bkmrk-email-name-sending-r" style="margin-left: 0pt;"><table style="border-width: initial; border-style: none; width: 107.901%; height: 475.906px;"><colgroup><col style="width: 63.3952%;" width="381"></col><col style="width: 36.6061%;" width="220"></col></colgroup><tbody><tr style="height: 43.3125px;"><td style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word; height: 43.3125px;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Email name</span>

</td><td style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word; height: 43.3125px;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Sending reason</span>

</td></tr><tr style="height: 69.3125px;"><td style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word; height: 69.3125px;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">BC\_USER\_PENDING\_TERMS\_AND\_CONDITIONS</span>

</td><td style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word; height: 69.3125px;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Sent while new terms and conditions are applied to the issuer to end users.</span>

</td></tr><tr style="height: 54.7812px;"><td style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word; height: 54.7812px;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">BC\_USER\_CARD\_EXPIRING</span>

</td><td style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word; height: 54.7812px;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Sent 1 day before card expiration to end user.</span>

</td></tr><tr style="height: 69.3125px;"><td style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word; height: 69.3125px;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">BC\_USER\_PENDING\_CARD</span>

</td><td style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word; height: 69.3125px;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Sent to end user when new card was assigned and is waiting for redemption</span>

</td></tr><tr style="height: 54.7812px;"><td style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word; height: 54.7812px;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">BC\_USER\_NEW\_CARD</span>

</td><td style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word; height: 54.7812px;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Sent to end user when new card was redeemed</span>

</td></tr><tr style="height: 54.7812px;"><td style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word; height: 54.7812px;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">BC\_USER\_CARD\_EXPIRED</span>

</td><td style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word; height: 54.7812px;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Sent to end user when approval is finished.</span>

</td></tr><tr style="height: 69.3125px;"><td style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word; height: 69.3125px;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">BC\_USER\_CARD\_DELETED</span>

</td><td style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word; height: 69.3125px;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Sent to end user while card/approval was uassigned or deleted by corporation.</span>

</td></tr><tr style="height: 60.3125px;"><td style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word; height: 60.3125px;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">BC\_USER\_CARD\_LOCKED</span>

</td><td style="vertical-align: top; padding: 5pt; overflow: hidden; overflow-wrap: break-word; height: 60.3125px;"><span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: 400; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Sent to end user when card was locked by corporation.</span>

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

</div>##### **4. Sparados Transaction API** 

**Description**

Sparados Transaction History API consists of inbound and outbound APIs*(Outbound API is only tagged because OAS version which is used in this document is elder than OAS 3.1 in which webhooks was introduced)*

**Inbound Authentication**

This API requires Mutual TLS authentication. You can use the same certificate for all mTLS-secured APIs exposed by Sparados. If you don't have one, follow this instruction: [Connecting to server-to-server APIs](https://developer.sparados.com/books/sparados-api-documentation/page/connecting-to-server-to-server-apis "Connecting to server-to-server APIs")

**Outbound Authentication**

During outbound call, server will present own certificate which is signed by Verestro (technology provider) CA and will proof possession of the private key during TLS handshake. Client can put configuration to trust all certificates signed by given CA. Every environment has own CA certificate and client has to use corresponding to environment root CA certificate

**Backward compatibility**

Any additional development in service will be backward compatible. Changes below are considered to be backward compatible, and client should not brake if any change will appear in future:

<div class="description" id="bkmrk-adding-a-new-endpoin"><div class="description"><div class="renderedMarkdown"><div><div><div>- adding a new endpoint.
- adding a new, optional, request parameter to an existing endpoint. The parameter can be added as part of the request body, as a URL parameter, or an HTTP header
- adding a new enum value. The value is added either in the request or in the response.
- relaxing some of the constraints on an existing request parameter. For example, making it optional
- adding a new response parameter to the API response

</div></div></div></div></div></div>Summing up: Client should ignore any unknown fields or enum values received as part of API responses

**Outbound Retry Strategy**

Outbound calls that fail with a timeout, connection failure, or an HTTP response code of 5xx, server will automatically retry 3 times with up to a 5-second wait between each try. If the call has not succeeded after the initial retries server will attempt a second round of 3 retries with increasing time intervals between each retry. Between attempts the system will wait 15 minutes, 30 minutes, and then 2 hours. If client server will not respond and retries are exhausted then call is dismissed

**Transaction API**

[https://developer.verestro.com/books/transaction-history-api/page/technical-documentation-thc-external-api](https://developer.verestro.com/books/transaction-history-api/page/technical-documentation-thc-external-api)

#### Cards API Swagger Documentation 

@swagger="https://sparados-bc-api.upaidtest.pl/api-secure.yaml"

# Full API Integration

Full API Integration is designed for partners who want to embed the full card issuing flow directly into their own system.

In this model, the partner does not use Sparados hosted mobile or web applications. Instead, the partner manages the end-user experience on its own side and communicates with Sparados APIs directly.

Full API Integration allows partners to:

- create users via API
- create cards via API
- manage card lifecycle
- retrieve and display card data, including PAN / CVV
- handle OTP and 3DS flows
- receive Apple Pay / Google Pay OTP notifications
- retrieve transactions and receive transaction notifications

This integration model gives the partner full control over the user and card flow, but may require PCI DSS compliance if sensitive card data is received, processed, stored, or displayed.

Before using Full API Integration, the partner must complete onboarding with Sparados, sign the cooperation agreement, and configure Mutual TLS authentication for 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>

##### **1. HOW FULL API INTEGRATION WORKS**

Full API documentation is available here:

[Swagger Full API Documentation](https://sp-api.verestro.dev/docs?urls.primaryName=External)

In the Full API model, the partner creates the end user and card directly through API.

The process starts with creating a user using:

`POST /secure/users/`

The partner must provide the required user details, including email, phone number, first name, last name, date of birth, and nationality.

After the user is created, Sparados returns `userId`.

The partner then creates an approval for this user and provides the received `userId` in the approval request body. In Full API Integration, after the approval is created, the card is generated automatically and the approval moves directly to `DELIVERED` status.

After creating the approval, the partner should poll the approval details endpoint to retrieve the generated `cardId`.

The recommended approach is to call:

`GET /secure/approvals/{approvalId}` every `0.5 second`<span class="s2"> until </span>`cardId`<span class="s2"> is returned and the approval status is </span>`DELIVERED`<span class="s2">.</span>

Once `cardId` is returned, the partner should store both `approvalId` and `cardId`, as these values are required for later card management and card data retrieval.

The partner should store both `approvalId` and `cardId`, as these values are required for later card management and card data retrieval.

[![UserAndCardCreation.png](https://developer.sparados.com/uploads/images/gallery/2026-05/scaled-1680-/userandcardcreation.png)](https://developer.sparados.com/uploads/images/gallery/2026-05/userandcardcreation.png)

**<span style="color: #000000;">  
</span>**

##### **2. VALUES USED IN SPARADOS CARDS API**

**Swagger documentation is in the end of document**

This section describes common value formats used across Sparados Cards API.  
These rules apply when creating approvals, defining card limits, setting validity periods, and managing card-related operations.

<span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Date format</span>

Sparados APIs use the ISO 8601 date and time format.

The expected format is:

```
YYYY-MM-DDTHH:mm:ss.SSSZ
```

<div class="relative w-full mt-4 mb-1" id="bkmrk--3"><div class=""><div class="relative"><div class="h-full min-h-0 min-w-0"><div class="h-full min-h-0 min-w-0"><div class="border border-token-border-light border-radius-3xl corner-superellipse/1.1 rounded-3xl"><div class="h-full w-full border-radius-3xl bg-token-bg-elevated-secondary corner-superellipse/1.1 overflow-clip rounded-3xl lxnfua_clipPathFallback"><div class="relative">  
</div></div></div></div></div></div></div></div>Where:

- `T` separates the date from the time
- `Z` represents Zulu time / UTC time

Example:

```
2023-05-22T10:00:01.953Z
```

<span style="color: rgb(0, 0, 0); font-family: Arial, sans-serif; font-size: 11pt; font-style: normal; font-variant-caps: normal; font-weight: bold; white-space-collapse: preserve;">Minor values</span>

All numeric amount values used in Sparados Cards API are provided in minor units.  
For example, to assign a card with a limit of `100.50 EUR`, send:

```
10050
```

This applies to values such as:

- card budget
- additional limits
- budget increases
- budget decreases

<span style="font-size: 11pt; font-family: Arial, sans-serif; color: #000000; background-color: transparent; font-weight: bold; font-style: normal; font-variant: normal; white-space-collapse: preserve;">Currency</span>

Card approvals are created in the currency of the account / balance. The currency does not need to be provided separately when creating an approval, because it is inherited from the selected account / balance.  
Each account can have only one currency. Transactions may still be performed in other currencies, depending on the card configuration and transaction rules.

##### <span class="s1">**3. USER MANAGEMENT**</span>

In Full API Integration, the partner manages end users directly through API.

The user must be created before an approval can be assigned directly to this user.

**User API Methods**

<table border="1" cellpadding="8" cellspacing="0" id="bkmrk-method-endpoint-desc" width="100%"><thead><tr><th>**Method**

</th><th>**Endpoint**

</th><th>**Description**

</th></tr></thead><tbody><tr><td>`POST`

</td><td>`/secure/users/`

</td><td>Creates a new end user.

</td></tr><tr><td>`GET`

</td><td>`/secure/users/{userId}`

</td><td>Retrieves details of a specific user.

</td></tr><tr><td>`PATCH`

</td><td>`/secure/users/{userId}`

</td><td>Updates selected user details.

</td></tr><tr><td>`DELETE`

</td><td>`/secure/users/{userId}`

</td><td>Deletes or deactivates the user, depending on the agreed configuration.

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

**Create User**

`POST /secure/users/`

Required fields:

<table border="1" cellpadding="8" cellspacing="0" id="bkmrk-field-type-descripti" width="100%"><thead><tr><th>**Field**

</th><th>**Type**

</th><th>**Description**

</th></tr></thead><tbody><tr><td>`email`

</td><td>`string`

</td><td>End user’s email address.

</td></tr><tr><td>`phoneNumber`

</td><td>`string`

</td><td>End user’s phone number.

</td></tr><tr><td>`firstName`

</td><td>`string`

</td><td>End user’s first name.

</td></tr><tr><td>`lastName`

</td><td>`string`

</td><td>End user’s last name.

</td></tr><tr><td>`dateOfBirth`

</td><td>`string`

</td><td>End user’s date of birth. Recommended format: `YYYY-MM-DD`.

</td></tr><tr><td>`nationality`

</td><td>`string`

</td><td>End user’s nationality. Recommended ISO country code, for example `PL`.

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

Example request:

```json
{
  "email": "john.smith@example.com",
  "phoneNumber": "48123456789",
  "firstName": "John",
  "lastName": "Smith",
  "dateOfBirth": "1990-01-01",
  "nationality": "PL"
}
```

Example response:

```json
{
  "id": 123456
}
```

The returned `userId` should be stored by the partner and used when creating an approval assigned directly to this user.

##### <span class="s1">**4. CREATING CARD APPROVALS**</span>

To create a card for an existing user, use the Approval API.

`POST /secure/approvals`

In Full API Integration, the partner does not provide user contact details in the approval request. The user must be created first through the User API, and the returned `userId` must be provided in the approval request body as `user.id`.

A card approval defines which user should receive the card, what budget can be used, how long the card should be valid, and what transaction limits should apply. After the approval is created and assigned to an existing user, the approval is first created with status `ACCEPTED`. Because the user already exists, the card is generated automatically and the approval then moves directly to `DELIVERED` status.

The API returns `approvalId`. The partner should store this value, as it is required for retrieving card details and managing the approval later.

**Warning**

The `balance.id` used in the Approval API is not the same balance identifier as the `balanceId` used in:

`GET /secure/balances/{balanceId}`

For Approval API methods, including:

`POST /secure/approvals`

you must use the <span class="s1">**Card Alias ID**</span> assigned to the account. This value can be copied from the Corporate Panel.

You can find it in the Corporate Panel:

1. Go to <span class="s1">**Accounts**</span><span class="s2">.</span>
2. Select the relevant account.
3. Click <span class="s1">**Copy Card Alias**</span><span class="s2">.</span>
4. Use the copied value as `balance.id` in the Approval API request.

The `balanceId`<span class="s2"> required for:</span>

`GET /secure/balances/{balanceId}`

is a different identifier. This value is provided by Sparados each time a new payment account is created.

**Request Body Fields**

Required fields are marked with `*`.

<table border="1" cellpadding="8" cellspacing="0" id="bkmrk-field-type-descripti-1" width="100%"><thead><tr><th>**Field**

</th><th>**Type**

</th><th>**Description**

</th></tr></thead><tbody><tr><td>`balance.id`<span class="s2">\*</span>

</td><td>`string`

</td><td>Balance ID / Card Alias ID assigned to your corporation. This value can be copied from the Corporate Panel.

</td></tr><tr><td>`user.id`<span class="s2">\*</span>

</td><td>`integer`

</td><td>ID of the existing user created through `POST /secure/users/`.

</td></tr><tr><td>`rules.budgetMinor`<span class="s2">\*</span>

</td><td>`integer`

</td><td>Total amount in minor units that the user can spend using the card.

</td></tr><tr><td>`rules.validityPeriod.startDate`<span class="s2">\*</span>

</td><td>`string`

</td><td>Start date and time of the card validity period in ISO 8601 format.

</td></tr><tr><td>`rules.validityPeriod.endDate`<span class="s2">\*</span>

</td><td>`string`

</td><td>End date and time of the card validity period in ISO 8601 format.

</td></tr><tr><td>`rules.validityPeriod.timezone`<span class="s2">\*</span>

</td><td>`string`

</td><td>Timezone used for the validity period, for example `Europe/Warsaw`.

</td></tr><tr><td>`rules.purpose.ecommerce`<span class="s2">\*</span>

</td><td>`boolean`

</td><td>Defines whether the card can be used for e-commerce transactions. Currently, this should be set to `true`.

</td></tr><tr><td>`rules.purpose.allowChangeRequest`

</td><td>`boolean`

</td><td>Defines whether the user can request changes to card limits or validity period.

</td></tr><tr><td>`rules.limits`

</td><td>`array`

</td><td>List of additional card limits.

</td></tr><tr><td>`card.description`

</td><td>`string / null`

</td><td>Description displayed on the card visual.

</td></tr><tr><td>`card.visual.id`

</td><td>`string`

</td><td>ID of the card visual. If not provided, the default card visual may be used.

</td></tr><tr><td>`tags`

</td><td>`array`

</td><td>List of tag IDs or tag values assigned to the approval.

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

**Additional limits**

It is possible to set additional limits on the card. These limits are optional. If they are not provided, the card issuing service will apply default values.

There are four main types of additional limits:

**General limit** — periodic limit for all types of transactions. This value should be greater than the other additional limits because it affects them. For example, if the ATM limit is set to `100 EUR` and the general limit is set to `50 EUR`, the end user will be able to withdraw only `50 EUR` from the ATM.

**Online payment limit** — periodic limit for e-commerce payments.

**ATM limit** — periodic limit for ATM withdrawals.

**Foreign transaction limit** — periodic limit for transactions in a currency different from the account currency. The limit is provided in the account / balance currency and is recalculated using exchange rates and commission.

Possible time units for all additional limits are:

`daily`

`weekly`

`monthly`

Possible values for additional limits:

`0` — disabled. The end user will not be able to perform this type of transaction.

Value in minor units — limited to the requested value.

`null` — unlimited. The end user will be able to perform this type of transaction without a specific additional limit.

**Difference between approval and reapproval**

An approval is created by the corporation in the process of assigning a card to a user.

In Full API Integration, the approval is assigned directly to an existing user by providing `user.id` in the request body.

A reapproval can be created when editing an approval that is already in `DELIVERED` status or when a change request flow is enabled.

##### <span class="s1">**5. APPROVAL STATUSES AND AVAILABLE ACTIONS**</span>

This section describes approval statuses and actions available in Full API Integration.

In Full API Integration, the approval is assigned directly to an existing user by providing `user.id` in the approval request body.

After the approval is created, it is initially created with status `ACCEPTED`. Because the user already exists, the card is generated automatically and the approval then moves directly to `DELIVERED` status.

**Approval Statuses**

<table border="1" cellpadding="8" cellspacing="0" id="bkmrk-status-description-a" width="100%"><thead><tr><th>**Status**

</th><th>**Description**

</th></tr></thead><tbody><tr><td>`ACCEPTED`

</td><td>Approval has been created and assigned to an existing user. This is usually a temporary status before the card is generated.

</td></tr><tr><td>`DELIVERED`

</td><td>Card has been generated and assigned to the user. This is the active status in which transactions can be made with the card.

</td></tr><tr><td>`FINISHED`

</td><td>Approval with status `DELIVERED` exceeded the end date of assignment.

</td></tr><tr><td>`REAPPROVED`

</td><td>Original approval status after a reapproval has been accepted and replaced the previous approval.

</td></tr><tr><td>`LOCKED`

</td><td>This is a card status, not an approval status. It is shown in the lifecycle because a card can be locked only when the approval is in `DELIVERED` status.

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

**Unassigning a card from a user**

To remove the card from the user, use:

`PUT /secure/approvals/{id}/unassign`

**Increasing or decreasing available budget**

To quickly increase the available budget on a card, use:

`PUT /secure/approvals/{id}/increase_budget`

Example: to add `10 EUR`, send:

```json
{
  "additionalBudgetMinor": 1000
}
```

To decrease the available budget, use the same endpoint with a negative value.

Example: to subtract `10 EUR`, send:

```json
{
  "additionalBudgetMinor": -1000
}
```

The value must be provided in minor units. For example, `10 EUR = 1000` minor units.

##### <span class="s1">**6. CHECKING ACCOUNT BALANCE**</span>

To check the balance of the payment account connected with issued cards, use:

`GET /secure/balances/{balanceId}`

This method returns the current balance of the account connected with cards.

The `balanceId` required for this method is provided by Sparados after the payment account is created for the partner.

**Important**

The `balanceId` used in this endpoint is different from the `balance.id` used in the Approval API.

For balance checking, use:

`GET /secure/balances/{balanceId}`

For card approval creation, use the <span class="s1">**Card Alias ID**</span> copied from the Corporate Panel:

`POST /secure/approvals`

Do not use the Approval API `balance.id` / Card Alias ID in the balance endpoint, and do not use the balance endpoint `balanceId` in Approval API requests.

#### <span class="s1">**7. CARD DATA RETRIEVAL**</span>

To retrieve encrypted card details, use:

`GET /secure/cards/{id}/sensitive`

This endpoint returns sensitive card data, including PAN and CVV, in encrypted form.

The `{id}` parameter is the `cardId` received from the approval details after the card has been generated.

**Encryption**

Card details are always returned as a JWE token.

To decrypt the response, the partner must provide an RSA public key with each request.

The card data is encrypted using the provided public key. Only the holder of the matching private key can decrypt the response.

**Requirements**

<table border="1" cellpadding="8" cellspacing="0" id="bkmrk-requirement-descript" width="100%"><thead><tr><th>**Requirement**

</th><th>**Description**

</th></tr></thead><tbody><tr><td>RSA key pair

</td><td>Minimum key size: `2048-bit`<span class="s1">.</span>

</td></tr><tr><td>Public key format

</td><td>Base64-encoded SPKI PEM.

</td></tr><tr><td>Request header

</td><td>Public key must be sent in the `Public-Key` header.

</td></tr><tr><td>Response format

</td><td>API returns encrypted payload as a JWE compact token.

</td></tr><tr><td>Encryption algorithm

</td><td>`RSA-OAEP-256 + A256GCM`<span class="s2">.</span>

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

**Request Header**

<table border="1" cellpadding="8" cellspacing="0" id="bkmrk-header-value-public-" width="100%"><thead><tr><th>**Header**

</th><th>**Value**

</th></tr></thead><tbody><tr><td>`Public-Key`

</td><td>Base64-encoded RSA public key in SPKI PEM format.

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

**Response Format**

```json
{
  "payload": "<JWE compact token>"
}
```

**Decrypted Payload Example**

After decrypting the JWE token, the payload contains card details:

```json
{
  "id": 123,
  "type": "VIRTUAL",
  "cardNo": "5414599451242598",
  "cvv": "111",
  "exp": "2031-05-31",
  "issuerCardId": "1111111111111111",
  "dcCorporationId": "7f846a2f-92b4-4094-a776-35cf3753ef51",
  "balanceId": "67716ba1-081b-4919-8aae-9fdbee10be23"
}
```

**Recommended Security Flow**

If card data should be visible only to the end user, the key pair should be generated on the frontend side.

Recommended flow:

1. The frontend generates a temporary RSA key pair.
2. The frontend keeps the private key locally, for example in the user session.
3. The frontend sends only the public key to the partner backend.
4. The partner backend forwards the public key to Sparados API in the `Public-Key` header.
5. Sparados returns encrypted card data as a JWE token.
6. The encrypted payload is forwarded back to the frontend.
7. The frontend decrypts the payload using the private key.
8. PAN and CVV are displayed only to the end user.

**Security Note**

Never send the private key to Sparados API or to the partner backend if the decrypted card data should be accessible only to the end user. Only the public key should be sent in the request header.

Accessing, processing, storing, or displaying PAN / CVV may require PCI DSS compliance.

##### <span class="s1">**8. SPARADOS TRANSACTION API**</span>

Sparados Transaction History API allows partners to retrieve transaction history and receive transaction notifications.

The API consists of two parts:

<table border="1" cellpadding="8" cellspacing="0" id="bkmrk-type-description-inb" width="100%"><thead><tr><th>**Type**

</th><th>**Description**

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

</td><td>API methods called by the partner to retrieve transaction data from Sparados.

</td></tr><tr><td>Outbound API

</td><td>Webhook notifications sent by Sparados to the partner system when transaction events occur.

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

Transaction API documentation is available here:

[`https://developer.verestro.com/books/transaction-history-api/page/technical-documentation-thc-external-api`](https://developer.verestro.com/books/transaction-history-api/page/technical-documentation-thc-external-api)

**Authentication**

**Inbound Authentication**

Inbound API calls require Mutual TLS authentication.

The same client certificate can be used for all mTLS-secured APIs exposed by Sparados.

If the certificate has not been configured yet, follow the section:

[Connecting Server-to-Server](https://developer.sparados.com/books/sparados-api-documentation/page/connecting-to-server-to-server-apis)

**Outbound Authentication**

For outbound webhook calls, Sparados presents its own server certificate during the TLS handshake.

The certificate is signed by Verestro CA. The partner system should be configured to trust certificates signed by the relevant Verestro CA.

Each environment has its own CA certificate, so the partner must use the correct root CA certificate for the selected environment.

**Backward Compatibility**

Future API changes will be backward compatible. The following changes may be introduced without breaking compatibility:

1. adding a new endpoint
2. adding a new optional request parameter
3. adding a new optional response field
4. adding a new enum value
5. relaxing validation rules for an existing parameter, for example making it optional
6. The partner system should ignore unknown fields and unknown enum values received in API responses.

**Outbound Retry Strategy**

If an outbound webhook call fails because of a timeout, connection issue, or HTTP `5xx` response, Sparados will retry the call automatically.

<table border="1" cellpadding="8" cellspacing="0" id="bkmrk-retry-stage-descript" width="100%"><thead><tr><th>**Retry stage**

</th><th>**Description**

</th></tr></thead><tbody><tr><td>Initial retries

</td><td>3 retries with up to 5 seconds between each attempt.

</td></tr><tr><td>Extended retries

</td><td>If the call still fails, Sparados performs 3 additional retries after 15 minutes, 30 minutes, and 2 hours.

</td></tr><tr><td>Final result

</td><td>If all retries fail, the webhook call is dismissed.

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

The partner endpoint should return a successful HTTP response after receiving and processing the notification.

#### <span class="s1">**9. OTP AND WALLET NOTIFICATION WEBHOOKS**</span>

In Full API Integration, Sparados can send OTP and wallet-related notifications to endpoints provided by the partner.

The partner must provide Sparados with the full webhook URLs that should be used for notification delivery.

Requests are signed with Verestro’s CA certificate.

The partner endpoint should return:

`204 No Content`

to confirm that the notification was received successfully.

**3DS OTP Notification**

This webhook is triggered when a 3DS OTP is generated for a card in your corporation.

**Endpoint**

`POST {3ds_otp_notification_url}`

The full endpoint URL is provided by the partner during integration setup.

**Request Body**

<table border="1" cellpadding="8" cellspacing="0" id="bkmrk-field-type-descripti-2" width="100%"><thead><tr><th>**Field**

</th><th>**Type**

</th><th>**Description**

</th></tr></thead><tbody><tr><td>`balanceId`

</td><td>`string`

</td><td>Balance ID related to the card.

</td></tr><tr><td>`currency`

</td><td>`string`

</td><td>Transaction currency.

</td></tr><tr><td>`merchantName`

</td><td>`string`

</td><td>Merchant name for the transaction.

</td></tr><tr><td>`otp`

</td><td>`string`

</td><td>3DS one-time password generated for the transaction.

</td></tr><tr><td>`cardId`

</td><td>`integer`

</td><td>Card ID.

</td></tr><tr><td>`userId`

</td><td>`integer`

</td><td>User ID assigned to the card.

</td></tr><tr><td>`amountMinor`

</td><td>`integer`

</td><td>Transaction amount in minor units.

</td></tr><tr><td>`cardLast4Digits`

</td><td>`string`

</td><td>Last 4 digits of the card number.

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

**Example Request Body**

```json
{
  "balanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "currency": "EUR",
  "merchantName": "Example Merchant",
  "otp": "123456",
  "cardId": 123,
  "userId": 456,
  "amountMinor": 1000,
  "cardLast4Digits": "2598"
}
```

**Expected Response**

`204 No Content`

**Wallet Notifications**

This webhook is triggered when a wallet notification event occurs for a card in your corporation.

It is used for Apple Pay / Google Pay related events, including activation code delivery and token status updates.

**Endpoint**

`POST {wallet_notifications_url}`

The full endpoint URL is provided by the partner during integration setup.

**Message Types**

<table border="1" cellpadding="8" cellspacing="0" id="bkmrk-messagetype-descript" width="100%"><thead><tr><th>`messageType`

</th><th>**Description**

</th></tr></thead><tbody><tr><td>`ACTIVATION_CODE_DELIVERY`

</td><td>Wallet activation code should be delivered to the end user.

</td></tr><tr><td>`TOKEN_ACTIVATED`

</td><td>Wallet token has been activated.

</td></tr><tr><td>`CARD_REMOVED_BY_CUSTOMER`

</td><td>Card has been removed from the wallet by the customer.

</td></tr><tr><td>`CARD_REMOVED_BY_ISSUER`

</td><td>Card has been removed from the wallet by the issuer.

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

**Request Body**

<table border="1" cellpadding="8" cellspacing="0" id="bkmrk-field-type-descripti-3" width="100%"><thead><tr><th>**Field**

</th><th>**Type**

</th><th>**Description**

</th></tr></thead><tbody><tr><td>`cardLast4Digits`

</td><td>`string`

</td><td>Last 4 digits of the card number.

</td></tr><tr><td>`tokenRequestorType`

</td><td>`string`

</td><td>Wallet provider / token requestor type.

</td></tr><tr><td>`messageType`

</td><td>`string`

</td><td>Wallet notification type.

</td></tr><tr><td>`activationMethodType`

</td><td>`string`

</td><td>Activation method type. Present only for `ACTIVATION_CODE_DELIVERY`.

</td></tr><tr><td>`activationMethodValue`

</td><td>`string`

</td><td>Activation method value. Present only for `ACTIVATION_CODE_DELIVERY`.

</td></tr><tr><td>`activationCode`

</td><td>`string`

</td><td>Wallet activation code. Present only for `ACTIVATION_CODE_DELIVERY`.

</td></tr><tr><td>`formFactor`

</td><td>`string`

</td><td>Device or wallet form factor.

</td></tr><tr><td>`cardId`

</td><td>`integer`

</td><td>Card ID.

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

**Example Request Body**

```json
{
  "cardLast4Digits": "2598",
  "tokenRequestorType": "APPLE_PAY",
  "messageType": "ACTIVATION_CODE_DELIVERY",
  "activationMethodType": "SMS",
  "activationMethodValue": "+48123456789",
  "activationCode": "123456",
  "formFactor": "PHONE",
  "cardId": 123
}
```

**Expected Response**

`204 No Content`

**Important**

The fields `activationCode`<span class="s2">, </span>`activationMethodType`<span class="s2">, and </span>`activationMethodValue`<span class="s2"> are present only when </span>`messageType`<span class="s2"> is:</span>

`ACTIVATION_CODE_DELIVERY`

##### <span class="s1">**10. API SWAGGER DOCUMENTATION**</span>

Detailed API documentation is available here:

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

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

</th></tr></thead><tbody><tr><td>Full API Swagger

</td><td>`https://sp-api.verestro.dev/docs?urls.primaryName=External`

</td></tr><tr><td>Cards API Swagger

</td><td>`https://sparados-bc-api.upaidtest.pl/api-secure.yaml`

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

</td><td>`https://developer.verestro.com/books/transaction-history-api/page/technical-documentation-thc-external-api`

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

Use the Swagger documentation as the source of detailed endpoint schemas, request parameters, response formats, and available enum values.