# Introduction #### **1. Introduction** 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 applications. - **Full API Integration** — embedded card issuing with full control over users, cards, card data, and authentication flows. **Choose Integration Type**

Feature	Simple API	Full API
Fast integration	1–2 days	~1 month
Use Sparados mobile app	Yes	No
Use Sparados web app	Yes	No
Dedicated branded web app	Optional	No
Dedicated branded OTP SMS / WhatsApp / Email	Optional	No
Create users via API	No	Yes
Create cards via API	Yes	Yes
Receive PAN / CVV	No	Yes
Receive OTP / 3DS	No	Yes
Apple Pay / Google Pay OTP	No	Yes
PCI DSS scope	No	Yes

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 and Mutual TLS authentication must be enabled for your environment. The next section explains how to prepare your environment, generate certificates, and connect to Sparados APIs securely.

#### 2. Getting Started / Environment Setup / Authentication ##### **Essential steps before calling Sparados API:** **1. Create an x509 Certificate for Server-to-Server Communication** 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") **2. Receive Corporation Information from Sparados** The Corporation ID corresponds to the OU field in the generated certificate. After Sparados signs the certificate, you will receive the following information from them: - Balance ID - Signed certificate (name: V-Sparados) - Optionally, you may also receive personalized visuals and their IDs for your cards. **3. API addresses **

Instance	BETA	PROD
Cards API	https://sparadosv2-bc-api.secure-verestro.dev/secure	https://sparadosv2-bc-api.secure-verestro.com/secure
Transaction API	https://services.upaidtest.pl/thc	https://services.upaid.pl/thc

**4. Assign Cards to Corporation Members** - Now, you can assign cards to your corporation members using the information received from Sparados. - Remember to save the `approvalId` on your side because it will be needed in case of editing it later. By following these steps, you'll be ready to call Sparados API with the necessary credentials and information for your corporation's budget control and card management. #### Swagger documentation is in the end of document #### **Values used in Sparados Cards API** Date format We use ISO 8601 standard: year-month-day-T-hour-minute-second-Z where T is constant separating the date from the time and Z is Zulu time (Greenwich Mean Time (GMT)). Example: 2023-05-22T10:00:01.953Z Minor values All numeric values used in our API are in minor. If you want to e.g. assign card with limit 100.50 EUR you have to send us 10050. Currency is not needed - it's always the same as currency of account/balance. Currency Card/approval is always created in the currency of account. Account can have only one currency although it is possible to make transactions in other currencies. ID We always use UUID format for IDs in our project. #### **How to assign card?** Use the endpoint **POST /secure/approvals** to initiate the process of assigning a card and provide the necessary data listed below. Required fields are signed with \*.

rules.budgetMinor \*	Amount in minor that user can spend using a card provided in the currency of account/balance.
rules.validityPeriod \*	validity of a card in UTC format
rules.timezone \*	BC API will adjust startDate and EndDate to exact time in provided timezone
limits.amountMinor	Additional periodic limit value in minor provided in the currency of account/balance.
limits.timeUnit	Available values: daily, weekly, monthly
limits.type	Available values: general, ecommerce, atm, foreign\_amount. Types are descibed below the table.
purpose.ecommerce \*	Now it should be always as true.
purpose.allowChangeRequest \*	True - user can send a request to change limits on card False - user can't send a request to change limits on card
user.email \*	E-mail on which will be sent information about assigned card.
user.prefix \*	Prefix of a phone number of a user that can be used for authorization purpose
user.phone \*	Phone number of a user that can be used for authorization purpose
balance.Id \*	Id of a balance created for you corporation
card.description	Description displayed on a card visual in user app
card.visual.Id	Id of visual provided by Sparados. Null - default Sparados visual.

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

Example: ``` https://kolombo.verestro.dev/api/projects/Sparados/sms/48728209827/history/latest ``` `phoneNumber` should contain country prefix without `+` and without spaces. Additional limits It's possible to set additional limits on the card, which are optional. If left null, the card issuing service will set default values. **There are four types of additional limits:** 1. General limit - 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. Possible values: amount in minor or null. 2. Online payment limit - periodic limit on e-commerce payments. Possible values: 0, amount in minor or null. 3. ATM limit - periodic limit on ATM withdrawals. Possible values: 0, amount in minor or null. 4. Foreign transaction limit - 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. Possible values: 0, amount in minor or null. Possible time units for all additional limits are daily, weekly, and monthly Possible values od the additional limits: 0 - disabled. End user won't be able to perform online payments, withdraw from ATM or transactions in foreign currencies. **Value in minor** - limited to requested value **Null** - unlimited. End user will be able to perform online payments, withdraw from ATM or transactions in foreign currencies. #### Difference between approval and reapproval: Approval 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 PUT /secure/approvals/. Reapproval can be created by the corporation while editing data on approval (using method PUT /secure/approvals/{id}) 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. Ensure that you provide all the required fields and follow the instructions to successfully assign a card with the specified limits and rules. #### **The actions you can perform on an approval along with the corresponding statuses and available actions:** **Statuses of approvals:**

CREATED	Occur only when mobile user request changes on reapproval.
ACCEPTED	When an Approval is created. It changes to DELIVERED status after registration is complete and card is redeemed by end-user.
CANCELED	When an Approval or Reapproval with status CREATED, ACCEPTED or PREPARED is cancelled by corporation.
REJECTED	When a Reapproval with status CREATED is rejected by corporation.
EXPIRED	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).
PREPARED	When approval has been ACCEPTED, redeemed by the end-user and is waiting for card generation. Card is generated on startDate of Approval.
DELIVERED	When mobile user redeemed card. This is the state of approval in which transactions can be made with a card.
FINISHED	When an Approval with status DELIVERED exceeds the end date of assignment.
REAPPROVED	When a reapproval is created for a given Approval that is in Accepted/Delivered status.
LOCKED	This is a status of a card (not an approval) 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.

Statuses of an Approval: ![image-1686858492185.png](https://lh5.googleusercontent.com/sYHHJyRS62QNuv4v1hAw0XszLFQQcYaRhvGJ91nUU6_wIiouXy5cKZofGdBp2HQJ7GWGYSqas2RohCsX_Sxnn4I9WtL-0axOBLr1h3gehHdCFQp1EwIml2eU9pfd2eOv-mOr0aemquAQLlZAljEPf7Q) Statuses of a Reapproval: ![image-1686858497780.png](https://lh6.googleusercontent.com/kaU_AL-130eWb5Jjl6ZzAW3-gSGk_7DRp7kzjj5lLlQXpsMER-gyVD-8z8KCt3YQrMOYXlIH_8hQ_7Qpds5htuKJ9wni3eXe3HUd5ExSF-RdffyxuGIzhg3LQvnrwU2pKWxtAbXqNskpfe9u4-S-040) **Actions available on approvals:** - Created: Accept, Reject, Edit, Cancel. - Accepted: Cancel - Preprared: Cancel - Delivered: Lock, Unassign, Edit - Locked: Unlock - Rejected: — - Expired: — - Finished: — #### **Important! Reapproval Acceptance:** - When a reapproval is accepted, its status changes to "Delivered." - 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. - Concurrently, the status of the original approval changes to "Reapproved." ##### **Unassign card from enduser** 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. 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. #### Increase or decrease available limit on a card To quickly increase the available limit on a card, use the PUT /secure/approvals/{id}/increase\_budget method. 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). To quickly decrease the available limit on a card, use the same method PUT /secure/approvals/{id}/increase\_budget but with a negative value. To subtract 10 EUR from the available limit, put the value: "additionalBudgetMinor": -1000. #### What e-mails are sent to the end user? E-mails can be adjusted to your corporation and sent in different language. Contact Sparados for details.

Email name	Sending reason
BC\_USER\_PENDING\_TERMS\_AND\_CONDITIONS	Sent while new terms and conditions are applied to the issuer to end users.
BC\_USER\_CARD\_EXPIRING	Sent 1 day before card expiration to end user.
BC\_USER\_PENDING\_CARD	Sent to end user when new card was assigned and is waiting for redemption
BC\_USER\_NEW\_CARD	Sent to end user when new card was redeemed
BC\_USER\_CARD\_EXPIRED	Sent to end user when approval is finished.
BC\_USER\_CARD\_DELETED	Sent to end user while card/approval was uassigned or deleted by corporation.
BC\_USER\_CARD\_LOCKED	Sent to end user when card was locked by corporation.

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

- 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

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"