Credit Management

Create Credit Wallet

POSThttps://api.sandbox.sovera.io/cards/v2/wallet/credits

The creation of a credit wallet is done through a POST call that carries the following structure:

{
  "userId": "string",
  "currency": "string",
  "description": "string",
  "time": 0,
  "limit": 0,
  "firstCutDate": "2024-08-06T09:48:23.648Z",
  "creditProductCode": "string"
}

{
  "success": true,
  "data": {
    "id": "string",
    "userId": "string",
    "currency": "USD",
    "description": "string",
    "limit": 0,
    "creationDate": "2024-07-30T07:26:52.9871618+00:00"
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

This call must be made by associating it with a previously created active userId.

The “currency” field must consider ISO 4217 codes. (For example, US Dollars would be entered with the code "USD").

The "description" field is used to name the wallet according to its intended use, but is not mandatory for creating a new wallet.

The "time" field defines the number of days that the credit line must remain active. This field is used to define the term of a revolving credit (see ReportPayCredit). If this field is omitted, the resulting revolving wallet will remain indefinitely active until manual cancellation.

The "limit" field sets the credit limit amount in cents that the wallet will have per month.

The “firstCutDate” is a timestamp value in format ISO 8601, that defines when the credit line will be regenerated and according to the creditProductCode specs, will generate the necessary charges.

Finally, the creditProductCode is a previously generated by Sovera’s team 3-numbers code that specifies the rules for the credit line that will be set for this new wallet.

Retrieve Credit Wallet

GEThttps://api.sandbox.sovera.io/cards/v2/wallet/credits/

The GET call for credit wallets allows you to retrieve the information associated with the queried walletId. This call is particularly important for checking the available balance in a wallet, the balance withheld due to pending transactions, internal wallet limits and the amount spent during the month.

https://api.sandbox.sovera.io/cards/v2/wallet/credits/{WALLET_ID}

{
  "success": true,
  "data": [
    {
      "id": "string",
      "userId": "string",
      "currency": "string",
      "description": "string",
      "limit": 0,
      "amountOwed": 0,
      "interestOwed": 0,
      "amountAvailable": 0,
      "minimumPaymentDue": 0,
      "creationDate": "2024-11-12T12:48:39.573Z"
    }
  ],
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

The total balance is reflected in the "balance" field of the successful 200 response to this call, while the balance withheld is reflected in the "amountWithheld" field.

All amounts are reflected in cents, meaning USD 1,000.00 would be represented as 100000.

To a recently created wallet, the fields internalWalletLimit and amountSpentMonth comes by default with value 0. To change the internalWalletLimit check Change Internal Wallet Limit POST.

The call may fail if an incorrect walletId is provided, in which case the Sovera API would respond with a HTTP 404 error.

{
  "success": false,
  "errors": [
    { "code": "NOT_FOUND", "message": "Wallet 'c4d165d1-xxxx-xxxx-xxxx-017f0c6facf8' not found" }
  ],
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

Report Pay Credit

POSThttps://api.sandbox.sovera.io/cards/v2/reports/pay/credits

The ReportPayCredit endpoint is aimed to users who have an active credit line. The payment value can be either corresponding or partial — in which case it may generate debtor interests — and is reported in order to restore credit through the user's walletId.

The value reported in reportedAmount will be split between capital and interest owed, according to the interestCapitalSplit configured in the credit product related to the walletId.

{
  "walletId": "string",
  "reportedAmount": 0,
  "currency": "string",
  "statement": "string"
}

{
  "success": true,
  "data": {
    "creationDate": "2024-08-07T15:52:55.407Z",
    "limit": "string",
    "amountAvailable": "string",
    "capitalPaid": 0,
    "interestPaid": 0
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

The field called reportedAmount determines the total amount that the user is reporting, which will be split between capital and interest and impact the available amount within the credit line.

The currency field corresponds to the currency of the wallet. The statement field can be used to leave a brief description of the operation performed.

If successful, the payment report will be generated with the specified data, and the call will return an HTTP 201 Created detailing the date on which the report was made, as well as the updated credit limit, available balance, and amounts allocated to capital and interest. A webhook notification is also sent (see notificationEnlist**)** to inform the report and its effects.

Otherwise, the Sovera API will respond with an HTTP 422 error. The most common errors may include:

Invalid or non-credit walletId.
Currency value does not match the original currency of the wallet.
reportedAmount greater than amount owed.

Report Pay Credit Capital

POSThttps://api.sandbox.sovera.io/cards/v2/reports/pay/credits/capital

The ReportPayCreditCapital endpoint is used by users who have an active credit line. It expects either a corresponding or partial payment — in partial cases generating debtor interests — in order to restore credit through their walletId.

This endpoint does not consider the interestCapitalSplit from the credit product (see changeInterestCapital**)**. It applies the full reported amount directly to the capital owed, without allocating any portion to interest — even if debtor interest exists.

{
  "walletId": "string",
  "amountToCapital": 0,
  "currency": "string",
  "statement": "string"
}

{
  "success": true,
  "data": {
    "creationDate": "2024-08-07T11:28:37.022Z",
    "limit": "string",
    "amountAvailable": "string",
    "capitalPaid": 0
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

The field called amountToCapital determines the amount that the user is reporting, which will be applied exclusively to capital and will impact the available credit amount within the line.

The currency field corresponds to the currency of the wallet.

The statement field can be used to leave a brief description of the operation performed.

If successful, the payment report will be generated with the specified data, and the call will return an HTTP 201 Created detailing the date on which the report was made, as well as the values of the card limit and the available balance. A webhook notification is also sent (see notificationEnlist**)** to inform the report and its effects.

Otherwise, the Sovera API will respond with an HTTP 422 error. The most common errors may include:

Invalid or non-credit walletId.
Currency value does not match the original currency of the wallet.
amountToCapital greater than amount owed.

Change Wallet Limit

PUThttps://api.sandbox.sovera.io/cards/v2/wallet/credits/limits

This method will be used to modify the limits previously established in the credit wallets of Sovera API users. The limit can only be increased because of accountable matters.

{
  "walletId": "string",
  "newLimit": 0,
  "currency": "string",
  "statement": "string"
}

{
  "success": true,
  "data": {
    "walletId": "string",
    "newLimit": 0
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

The call will be associated with the provided 'walletId', followed by the value entered in the 'newLimit' field, which will represent the amount that needs to be updated in the 'limit' property of the wallet.

The 'currency' field must correspond to the 'currency' property of the indicated wallet, and finally, the 'statement' field provides a brief description of the operation performed.

All amounts are reflected in cents, meaning USD 1,000.00 would be represented as 100000.

On success, the API responds with HTTP 200 OK, echoing the updated walletId and newLimit.

The call may fail if an incorrect walletId is provided, in which case the Sovera API responds with a HTTP 404 error. If a smaller value is sented in newLimit, the Sovera API responds with a HTTP 422 error.

Update Credit Product Settings

PUThttps://api.sandbox.sovera.io/cards/v2/wallet/credits/interests

This endpoint fills the purpose of customize as you wish an instance of a credit product related to a specific wallet. You can change a lot of specifics properties from this credit product based on your own criteria. The description for each field is described on credit products session.

Although, is required that the credit product allows this operation to happen. You can check it contacting Sovera's team to get this information, although we recommend that every credit product created should be documented and stored properly.

{
  "walletId": "string",
  "interestRate": 0,
  "interestFixedAmount": 0,
  "morosidadRate": 0,
  "morosidadFixedAmount": 0,
  "minimumPaymentRate": 0,
  "minimumPaymentFixed": 0,
  "split": 0
}

{
  "success": true,
  "data": {
    "walletId": "string",
    "interestRate": 0,
    "interestFixedAmount": 0,
    "morosidadRate": 0,
    "morosidadFixedAmount": 0,
    "minimumPaymentRate": 0,
    "minimumPaymentFixed": 0,
    "split": 0
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

On success, the API responds with HTTP 200 OK, echoing the updated credit-product settings.

Only credit wallets are allowed to use this endpoint. If provided a debit wallet, the endpoint will respond with a HTTP 422 error.

The API will also respond with the same error if the userId associated with it is block or inactive. It is recommended to verify the status of the user associated prior to making the ChangeInterestCreditCapital call.

Check Credit Operation

GEThttps://api.sandbox.sovera.io/cards/v2/credit/checks/

The CheckCreditOperation GET call allows for retrieving information about a queried 'walletId'. This call is especially important for checking the activity status of the wallet.

If successful, the call will return an HTTP 200 detailing the associated 'walletId' and the status of the wallet."

https://api.sandbox.sovera.io/cards/v2/credit/checks/{WALLET_ID}

{
  "success": true,
  "data": {
    "walletId": "string",
    "status": "string"
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

Not found. An unknown walletId returns HTTP 404: {"success":false,"errors":[{"code":"NOT_FOUND","message":"Wallet '{walletId}' not found"}],"meta":{"timestamp":"2026-06-04T17:50:15.334Z","version":"v2","traceId":"73a5d32a-f92c-41eb-af8d-d7c6435f9a06"}}

The value of the 'status' attribute can be:

True if the wallet is activated and available for transactions.
False if it is blocked, either by the system or due to non-payment (see ReportPayCredit).