Credit Operations Flow

As an alternative to the debit and prepaid based systems, the credit core gives you the flexibility to offer credit lines to your users based on your own criteria. This feature allows you to configure and manage credit lines to individual user profiles.

With the credit core, users are assigned credit wallets linked to specific credit line settings. From there, they can begin making transactions using their available credit, just as they would with the balance of a prefunded wallet.

Credit Products

It is the heart of our credit core as it is what governs how each credit line will behave over time. Think of it as the "rule-book" that defines the terms and conditions of credit usage for your users.

Each credit wallet issued to a user is tied to a credit product, which ensures consistent behavior across similar credit lines and allows you to manage risk, profitability and flexibility with precision and granularity.

They are provided by Sovera based on agreements/requests with the clients previously. You can have as much credit products as you consider necessary although every credit product request is reviewed internally to avoid conflicts or misunderstandings on how it scales over time.

It is build to be as granular as possible, you can control from basic settings as grace period, cut frequency and interest rate. Until the more specific ones such as base minimum payment rate, if it is revolving or not, the capital interest split, etc.

The full list of adjustable parameters can be found in the table below:

Interest Accrual Methods

Sovera supports two interest accrual methods for credit lines associated with wallets: Average Daily Balance (ADB) and Balance at Cut. The accrual method is defined by the creditProductCode used during wallet creation via the POST /v2/wallet/credits endpoint.

1. Average Daily Balance (ADB)

In the ADB method, interest is calculated based on the average of daily balances recorded throughout the billing cycle. The process is as follows:

• The annual effective interest rate (annualInterestRate) is divided by a configurable parameter called rateDivisor, which may be 360 or 365.

  dailyInterestRate = annualInterestRate / rateDivisor

• At the end of each day during the cycle, the wallet’s balance is recorded and accumulated into the sumOfDailyBalance.

• At the end of the cycle (cutDate), the interest generated is calculated as:

  interestGenerated = dailyInterestRate * sumOfDailyBalance

• After the grace period (defined by gracePeriod in the credit product), the interest is applied. It may be:

  • Capitalized: added to the amountOwed (principal), or

  • Non-capitalized: added to interestOwed, without affecting the principal.

Note: Whether interest is capitalized is controlled by the compound parameter in the credit product.

2. Balance at Cut

With this method, interest is calculated based solely on the balance owed at the time of the cycle cut.

• On the cut date (cutDate), the current amountOwed is retrieved.

• The daily interest rate (same formula as in ADB) is applied directly to this balance:

  interestGenerated = baseInterestRate * amountOwed + fixedInterestAmount

• At the end of the grace period, the generated interest is applied:

  • Capitalized or not, depending on the credit product configuration.

This method does not take into account the balance changes throughout the cycle—only the state at the cut date matters.

Related Parameters

Credit Notifications

Notifications from Sovera's credit core are sent via webhooks. These events allow clients to stay in sync with changes to wallet balances, interest, limits, and more. To receive these events, register a callback URL via the NotificationsEnlist endpoint.

Notification Workflow

1. Client registers creditNotificationsURL once per environment.

2. Sovera validates the URL and starts sending webhook POST requests in near real-time.

3. Your system should verify the signature, parse the JSON, and update your internal records accordingly.

Event Payload Format

Each webhook follows a standard structure:

{
  "walletId": "string",
  "type": "Event Type String",
  "amount": 1234,
  "direction": "debit" | "credit",
  "affectsBalance": true,
  "walletDetails_after": {
    "principal_outstanding": 81500,
    "interest_accrued": 1200,
    "totalDebt": 82700,
    "limit": 12345,
    "amountOverdraft": 1234,
    "interestSpecs": {
      "interestRateNominal": 1234,
      "interestRateMoroso": 1234,
      "fixedInterestNominal": 1234,
      "fixedInterestMoroso": 1234
    },
    "minimumPaymentSpecs": {
      "minimumPaymentRate": 1234,
      "fixedMinimumPayment": 1234
    }
  }
}

Supported Event Types

Reading the post-event wallet state

The walletDetails_after object represents the full post-event state of the wallet. Fields like principal_outstanding, interest_accrued, and totalDebt should be used to refresh your internal state immediately.

Even if an event doesn't affect balances directly (e.g. interest calculated but not applied), this object reflects the most up-to-date ledger status.

Wallet Creation

Once you have (1) an approved credit product (creditProductCode) and (2) a callback URL for credit notifications, you can open your first credit wallet with the Wallet Credit POST endpoint.

A credit wallet is a ledger that tracks borrowing against an assigned limit. It never carries a positive cash balance—only counters for AA (available amount), AO (outstanding principal), and IO (outstanding interest).

Send a POST /v2/wallet/credits with the following JSON body:

Note
The field time is optional. If time is omitted, the wallet remains active indefinitely (subject to your own program rules).

After the call returns HTTP 201 with the wallet id, you may immediately link cards or virtual PANs to this wallet. All subsequent events—interest accruals, limit changes, payments, and so on—will be delivered to the callback URL you registered in Credit Notifications, keeping your internal ledgers and user interfaces in sync with Sovera’s credit core.

Credit Usage

Once a credit wallet is linked to one or more cards, the cardholder can spend up to the wallet’s limit during each billing cycle. Every purchase reduces the available amount (AA)—no funds are ever drawn from a cash balance.

Day‑to‑Day Management

Cycle Close, Grace Period, and Default Status

1. Cycle close (firstCutDate + cutFrequency)

   • The credit core calculates Interes nominal calculado (regular interest) and sends the corresponding webhook.

2. Grace period (gracePeriod days after the cut date)

   • During this window the customer must submit one or more ReportPayCredit calls whose combined amount satisfies the minimum payment rule configured in the credit product:

     minimumPayment = baseMinimumPaymentRate × AO + fixedMinimumPaymentAmount

3. Missing the minimum

   • If the required minimum is not met by grace‑period end, the wallet enters default status.

   • The system generates Interes moroso calculado (penal interest) and, after execution, Interes moroso ejecutado. These amounts are added to IO on top of any nominal interest already owed, so the debt grows faster the longer it remains unresolved.

4. Returning to good standing

   • The wallet exits default status once the sum of reported payments in the current cycle covers the minimum payment as defined above plus any executed penal interest.

   • A qualifying payment triggers an Interes cancelado webhook and, for revolving products, Credito Reintegrado, replenishing AA accordingly.

Because penal (“moroso”) interest can compound on top of regular (“nominal”) interest, remaining in default quickly becomes costly. Promptly reporting at least the calculated minimum payment keeps the wallet current and prevents additional charges.

Credit Operations

Administering Existing Credit Wallets

The credit core gives you fine‑grained control over each wallet. With a small set of endpoints you can:

• Block or unblock a wallet temporarily

• Increase a wallet’s credit limit

• Dissolve a wallet permanently

• Override interest parameters for an individual wallet (when permitted)

Block vs. Dissolve

Increasing the Credit Limit

Use ChangeWalletLimit to raise the wallet’s limit. Limits can only move upward; reductions are disallowed to avoid stranding unsettled authorisations.

Wallet‑Level Interest Overrides

If the associated credit product has variableSpecs = true, you may fine‑tune certain interest settings for one wallet without affecting any others. Submit ChangeInterestCreditCapital with the fields you wish to override; the changes activate at the next cut date and are confirmed via the Cambio Interest ejecutado webhook.

Note
Overrides are ignored when variableSpecs is false, ensuring that products intended to remain uniform cannot be altered at wallet level.