The Developer's Guide to Embedded Card Infrastructure: Sparados Full API
Sparados Full API is designed for companies that want to issue and manage cards directly from their own system, without using the Sparados web or mobile interface as the main operational layer. In this model, the partner is responsible for the frontend, business logic, user experience, customer communication, 3DS communication flow and transaction event handling. Sparados provides the API layer responsible for user creation, approval creation, automatic card issuing, card limits, sensitive card data delivery through JWE, webhooks and transaction data.
Table of Contents:
Core Architecture and Object Model
The architecture of the Full API is based on several core objects: user, approval, card and balance.
User: Represents the end user for whom the card will be issued.
Approval: A technical and business object that connects the user with the card, the available budget, the validity period and the usage rules.
Card: Represents the virtual payment instrument.
Balance: Represents the funding source used by the card.
In practice, the integration consists of creating a user, creating an approval for that user, waiting until the approval reaches the DELIVERED status, storing the returned cardId and then managing the card lifecycle through the API.
Step 1: User Creation
The first step is to call POST /secure/users/. The partner’s system sends user data such as email, phone, firstName, lastName, dateOfBirth and nationality. The API returns a user identifier, which is later used when creating the approval. This step is required because in the Full API model the corporate card is not created only from an email address or phone number. The card must be linked to an existing user record in Sparados.
Step 2: Approval Creation and Polling
The second step is to create an approval using POST /secure/approvals. The request body contains, among other fields, user.id, balance.id, currency, amountMinor, validFrom, validTo, timezone, e-commerce settings and optional card limits.
Technical Note on Amounts: amountMinor is always sent in minor units, so 100 EUR should be sent as 10000, and 99.99 EUR as 9999.
Dates should be passed in ISO 8601 format. This endpoint starts the card issuing process. After the approval is created, the partner’s system should poll GET /secure/approvals/{approvalId} until the approval reaches the DELIVERED status and returns cardId.
Understanding Approval Statuses
Approval statuses are important for the correct implementation of the flow. Receiving a successful response from the approval creation endpoint does not mean that the card is already ready to use. In a typical flow, the approval first reaches ACCEPTED and then DELIVERED.
Only the DELIVERED status means that the card has been generated and can be used for further operations. The partner’s system should treat this process as asynchronous and should not assume that cardId will always be available immediately after the first response from POST /secure/approvals.
The Balance Identifier Distinction
One important implementation detail is the difference between balance.id and balanceId.
balance.id (used when creating the approval) is the Card Alias ID assigned to the funding source.
balanceId (used in GET /secure/balances/{balanceId}) is a different identifier provided by Sparados.
Mixing these values is a common source of integration errors, especially when the partner manages multiple currencies, accounts or card programmes in one system.
Card Limits and Dynamic Budget Management
Card limits are configured at the approval level. The partner can define the main card budget, the card validity period and additional periodic limits. The Full API also allows the available card budget to be changed after the card has been issued. Reducing the available budget is done by sending a negative value. This allows the partner’s system to adjust the available card amount dynamically, based on its own business logic, such as claim status, approved cost, order value, customer balance or operator decision.
Securing Sensitive Card Data via JWE
Sensitive card data is retrieved through the card sensitive data endpoint, which returns the payload as a JSON Web Encryption (JWE) token. The partner sends a Public-Key header containing a base64 encoded RSA public key in SPKI PEM format. Sparados encrypts the response using RSA-OAEP-256 and A256GCM. The response can only be decrypted with the matching private key.
The recommended model is to generate the key pair on the client side or in another trusted application layer, send only the public key to Sparados and decrypt the JWE outside of the backend layer that should not log, store or process PAN, CVV or expiry date in plain text.
PCI DSS Compliance and Backend Security
This is the most security-sensitive part of the integration. The Full API gives the technical ability to retrieve card data, but the partner decides where the data is decrypted, whether it is stored, whether it appears in logs, whether it passes through the backend and what part of the environment may fall under PCI DSS scope. Using JWE does not automatically remove all card data security obligations. If the partner’s backend has access to plain card data, it should be treated as part of the card data environment.
Read more about PCI DSS: Demystifying PCI DSS: Choosing Your Sparados Integration Path
Transport Security via mTLS
Server-to-server communication is protected by mutual TLS (mTLS). The API client must use a client certificate, and the TLS connection is authenticated on both sides. In practice, this means that the partner must correctly configure certificates in its backend environment, separate test and production certificates and manage certificate rotation. This adds implementation complexity, but it is a suitable model for financial APIs where a static API token would not provide a sufficient level of access control.
Webhook Architecture: 3DS and Digital Wallets
The Full API uses webhooks to communicate asynchronous events:
3DS Webhook: Allows Sparados to send the partner the data required to handle e-commerce transaction authentication, including OTP, amountMinor, currency, merchantName, cardId, userId and the last four digits of the card. This allows the partner to deliver the authentication message to the user through its own channel, such as SMS, email, push notification or in-app messaging.
Wallet Webhook: Informs the partner about events related to Apple Pay and Google Pay tokenisation, such as activation code delivery, token activation or card removal from the wallet.
Webhook Best Practices and Idempotency
Webhook endpoints on the partner side should be idempotent. The same event may be delivered more than once, so the system should not execute irreversible operations only because a single request was received. A proper implementation should support retries, timeouts, request source validation, fast HTTP responses and asynchronous processing of business operations. The webhook should not block on long-running internal workflows.
Transaction Handling and Resource Mapping
Transactions are handled through the Transaction API. The partner can retrieve transaction data and receive transaction events to map card payments to its own business objects. Depending on the use case, this may be an assistance case, employee expense, claim, order, booking, payout or another object in the partner’s system.
From an integration perspective, it is important to store the relationship between userId, approvalId, cardId, balanceId and the partner’s own business identifier. Without this mapping, reconciliation and dispute handling become unnecessarily difficult.
Architectural Trade-Offs: Strengths and Weaknesses
Strengths | Weaknesses |
• Full control over the frontend and UX • No external interface redirection required • Automated card issuance via API • Programmable limits and dynamic budget changes • Encrypted sensitive data delivery (JWE) • Webhooks for 3DS and mobile wallets • Robust transport security via mTLS | • Higher technical and architectural complexity • Mandatory client certificate management • Complex webhook and idempotency design • Strict reliance on custom identifier mapping • PCI DSS compliance considerations • Need to build custom card display interfaces • Partner must maintain custom retry/reconciliation logic |
Ideal Use Cases for the Full API Model
Full API is the right model when the virtual card is supposed to be part of an existing product, not a separate flow handled in an external panel. It works best for systems that already have their own users, approval workflows, frontends and internal business logic. In this setup, Sparados acts as the issuing API layer, while the partner keeps absolute control over the application, user communication and operational process.
