Cards

Issue and Retrieve Cards

Issue debit, credit and prepaid cards against any user wallet, and pull card metadata back.

Create Debit Card

POSThttps://api.sandbox.sovera.io/cards/v2/debit/cards

This call enables the creation of a Debit Card and follows the following structure:

{
  "userId": "string",
  "walletId": "string",
  "physicalCard": true,
  "code": "string"
}
{
  "success": true,
  "data": {
    "id": "string",
    "userId": "string",
    "walletId": "string",
    "physicalCard": true,
    "code": "string",
    "isActive": true,
    "status": "string",
    "creationDate": "2022-08-01T19:37:50.392Z",
    "dueDate": 0
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

Each request includes the userId to whom the card should be associated and the walletId whose balance the card will be transacting with.

The physicalCard field indicates whether it is a card that needs to be printed physically (true) or, alternatively, an exclusively digital card (false).

The card printing data is extracted from the fields stored in the user creation, so it is important to note that the cards are printed taking into account the FirstName and LastName fields in the case of natural persons and the RegisteredName field in the case of legal entities. It is essential to ensure the integrity of these fields in the user creation flow, including character limitations, since it affects the subsequent card creation flow.

The "code" sent in the call must be provided by the Sovera team for each type and variation of card included in the enablement project. That is, for a project that enables the issuance of a virtual or physical debit card for natural persons, two different codes would be provided, one for endUser physical and one for endUser virtual. It is the client's responsibility to correctly invoke the calls taking into consideration the type of user and the printing condition associated with the provided code.

The successful response of the debit card creation call returns a 201 Created message that carries the unique identifier of the card that must be used in all card operation calls (see cardOperations). In addition to the cardId, the 201 Created response also provides a boolean indicating whether the card is operational or not, and a status field describing the card's status.

The possible statuses are detailed below:

  • PendingAck - For newly created physical cards that have not been activated. (see AckReception POST)

  • Temporarilyblocked - For self-manageable blocks. (see UnblockCard POST)

  • Cancel - For canceled cards (see CancelCard POST)

  • Active - For active cards

The sensitive card data (PAN and CVV) can be queried using the checkPan POST and checkCvv POST calls. However, it is important to note that such data must NOT be stored in databases as they imply cybersecurity requirements associated with the PCI standard that have been abstracted with the use of the cardId in the Sovera API.

The card's expiration date is presented in the successful response of the card creation call in the "dueDate" field following the format YYYYMM.

Prerequisite: the user must be ACTIVE. A card can only be created for an active user. A managed end user is created with isActive=false and stays inactive until KYC is completed, so card creation fails with HTTP 422 ("User not active") until KYC is done. A delegated (EndUserDelegated) user is active immediately and can receive a card right away.

In case of any error or inconsistency with the provided data, the API will respond with a descriptive 422 error of one of the most common possible reasons:

  1. The userId to which the card is to be associated does not exist or is inactive.
  2. The walletId to which the card is to be associated does not exist or does not belong to the entered user.
  3. The code provided in the call does not match the type of user to which the card is to be associated.
  4. The code provided in the call does not match the type of card (virtual or physical) being attempted to create.

A validation error is returned as:

{
  "success": false,
  "errors": [ { "code": "VALIDATION_ERROR", "message": "The walletId does not belong to the entered user.", "field": "walletId" } ],
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

It is important to note that retries in case of errors must be managed responsibly, i.e., by creating time limits of at least 5 seconds before the retry and limiting the number of retries to 3.

Retrieve Debit Card

GEThttps://api.sandbox.sovera.io/cards/v2/debit/cards/

The GET call for debit cards allows you to query the data of a card based on a cardId.

https://api.sandbox.sovera.io/cards/v2/debit/cards/{DEBIT_CARD_ID}
{
  "success": true,
  "data": [
    {
      "id": "string",
      "userId": "string",
      "walletId": "string",
      "physicalCard": true,
      "code": "string",
      "isActive": true,
      "status": "string",
      "creationDate": "2024-11-12T17:09:56.722Z",
      "dueDate": "string"
    }
  ],
  "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 and returns the card's current data.

This call is especially necessary in managing the transaction status of the card, since the successful response also includes the "isActive" boolean activity and the descriptive "status" field, in addition to the other fields in the successful response of card creation.In case an invalid cardId is sent, the Sovera API will respond with an HTTP 404 error.

If there is a HTTP 500 error encountered, report the incident to the Sovera support team.

Not found. An unknown cardId returns HTTP 404:

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

Create Prepaid Card

POSThttps://api.sandbox.sovera.io/cards/v2/prepaid/cards

This is the call used to create prepaid cards associated with a particular userId and walletId, and it carries the following structure:

{
  "userId": "string",
  "walletId": "string",
  "physicalCard": true,
  "code": "string"
}
{
  "success": true,
  "data": {
    "id": "string",
    "userId": "string",
    "walletId": "string",
    "physicalCard": true,
    "code": "string",
    "isActive": true,
    "status": "string",
    "creationDate": "2024-11-12T17:11:55.775Z",
    "dueDate": "string"
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

Each request includes the userId to whom the card should be associated and the walletId whose balance the card will be transacting with.

The physicalCard field indicates whether it is a card that needs to be printed physically (true) or, alternatively, an exclusively digital card (false).

The card printing data is extracted from the fields stored in the user creation, so it is important to note that the cards are printed taking into account the FirstName and LastName fields in the case of natural persons and the RegisteredName field in the case of legal entities. It is essential to ensure the integrity of these fields in the user creation flow, including character limitations, since it affects the subsequent card creation flow.

The "code" sent in the call must be provided by the Sovera team for each type and variation of card included in the enablement project. That is, for a project that enables the issuance of a virtual or physical debit card for natural persons, two different codes would be provided, one for endUser physical and one for endUser virtual. It is the client's responsibility to correctly invoke the calls taking into consideration the type of user and the printing condition associated with the provided code.

The possible statuses are detailed below:

  • PendingAck - For newly created physical cards that have not been activated. (see AckReception POST)

  • Temporarilyblocked - For self-manageable blocks. (see UnblockCard POST)

  • Cancel - For canceled cards (see CancelCard POST)

  • Active - For active cards

The sensitive card data (PAN and CVV) can be queried using the checkPan POST and checkCvv POST calls. However, it is important to note that such data must NOT be stored in databases as they imply cybersecurity requirements associated with the PCI standard that have been abstracted with the use of the cardId in the Sovera API.

The card's expiration date is presented in the successful response of the card creation call in the "dueDate" field following the format YYYYMM.

Prerequisite: the user must be ACTIVE. A card can only be created for an active user. A managed end user is created with isActive=false and stays inactive until KYC is completed, so card creation fails with HTTP 422 ("User not active") until KYC is done. A delegated (EndUserDelegated) user is active immediately and can receive a card right away.

In case of any error or inconsistency with the provided data, the API will respond with a descriptive 422 error of one of the most common possible reasons:

  1. The userId to which the card is to be associated does not exist or is inactive.
  2. The walletId to which the card is to be associated does not exist or does not belong to the entered user.
  3. The code provided in the call does not match the type of user to which the card is to be associated.
  4. The code provided in the call does not match the type of card (virtual or physical) being attempted to create.

A validation error is returned as:

{
  "success": false,
  "errors": [ { "code": "VALIDATION_ERROR", "message": "The walletId does not belong to the entered user.", "field": "walletId" } ],
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

It is important to note that retries in case of errors must be managed responsibly, i.e., by creating time limits of at least 5 seconds before the retry and limiting the number of retries to 3.

Retrieve Prepaid Card

GEThttps://api.sandbox.sovera.io/cards/v2/prepaid/cards/

The GET call for prepaid cards allows you to query the data of a card based on a cardId.

https://api.sandbox.sovera.io/cards/v2/prepaid/cards/{PREPAID_CARD_ID}
{
  "success": true,
  "data": [
    {
      "id": "string",
      "userId": "string",
      "walletId": "string",
      "physicalCard": true,
      "code": "string",
      "isActive": true,
      "status": "string",
      "creationDate": "2024-11-12T17:09:56.722Z",
      "dueDate": "string"
    }
  ],
  "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 and returns the card's current data.

This call is especially necessary in managing the transaction status of the card, since the successful response also includes the "isActive" boolean activity and the descriptive "status" field, in addition to the other fields in the successful response of card creation.In case an invalid cardId is sent, the Sovera API will respond with an HTTP 404 error.

If there is a HTTP 500 error encountered, report the incident to the Sovera support team.

Not found. An unknown cardId returns HTTP 404:

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

Create Credit Card

POSThttps://api.sandbox.sovera.io/cards/v2/credit/cards

This call enables the creation of a Credit Card associated to a particular userId and walletId. The following structure must be kept to send the relevant data.

{
  "userId": "string",
  "walletId": "string",
  "physicalCard": true,
  "code": "string"
}
{
  "success": true,
  "data": {
    "id": "string",
    "userId": "string",
    "walletId": "string",
    "physicalCard": true,
    "code": "string",
    "isActive": true,
    "status": "string",
    "creationDate": "2024-11-12T17:17:42.133Z",
    "dueDate": "string"
  },
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

In each call, the userId to which the card should be associated and the walletId with whose balance the card will be transacting are included.

For credit cards, the walletId to be associated must be a credit wallet (see WalletCredits) or a prepaid wallet with the "walletType" attribute equal to "1".

The physicalCard field indicates whether it is a card that needs to be printed physically (true) or, alternatively, an exclusively digital card (false).

The card printing data is extracted from the fields stored in the user creation, so it is important to note that the cards are printed taking into account the FirstName and LastName fields in the case of natural persons and the RegisteredName field in the case of legal entities. It is essential to ensure the integrity of these fields in the user creation flow, including character limitations, since it affects the subsequent card creation flow.

The "code" sent in the call must be provided by the Sovera team for each type and variation of card included in the enablement project. That is, for a project that enables the issuance of a virtual or physical debit card for natural persons, two different codes would be provided, one for endUser physical and one for endUser virtual. It is the client's responsibility to correctly invoke the calls taking into consideration the type of user and the printing condition associated with the provided code.

The successful response of the debit card creation call returns a 201 Created message that carries the unique identifier of the card that must be used in all card operation calls (see cardOperations). In addition to the cardId, the 201 Created response also provides a boolean indicating whether the card is operational or not, and a status field describing the card's status.

The possible statuses are detailed below:

  • PendingAck - For newly created physical cards that have not been activated. (see AckReception POST)

  • Temporarilyblocked - For self-manageable blocks. (see UnblockCard POST)

  • Cancel - For canceled cards (see CancelCard POST)

  • Active - For active cards

The sensitive card data (PAN and CVV) can be queried using the checkPan POST and checkCvv POST calls. However, it is important to note that such data must NOT be stored in databases as they imply cybersecurity requirements associated with the PCI standard that have been abstracted with the use of the cardId in the Sovera API.

The card's expiration date is presented in the successful response of the card creation call in the "dueDate" field following the format YYYYMM.

Prerequisite: the user must be ACTIVE. A card can only be created for an active user. A managed end user is created with isActive=false and stays inactive until KYC is completed, so card creation fails with HTTP 422 ("User not active") until KYC is done. A delegated (EndUserDelegated) user is active immediately and can receive a card right away.

In case of any error or inconsistency with the provided data, the API will respond with a descriptive 422 error of one of the most common possible reasons:

  1. The userId to which the card is to be associated does not exist or is inactive.
  2. The walletId to which the card is to be associated does not exist or does not belong to the entered user.
  3. The code provided in the call does not match the type of user to which the card is to be associated.
  4. The code provided in the call does not match the type of card (virtual or physical) being attempted to create.

A validation error is returned as:

{
  "success": false,
  "errors": [ { "code": "VALIDATION_ERROR", "message": "The walletId does not belong to the entered user.", "field": "walletId" } ],
  "meta": {
    "timestamp": "2026-06-04T17:50:15.334Z",
    "version": "v2",
    "traceId": "73a5d32a-f92c-41eb-af8d-d7c6435f9a06"
  }
}

It is important to note that retries in case of errors must be managed responsibly, i.e., by creating time limits of at least 5 seconds before the retry and limiting the number of retries to 3.

Retrieve Credit Card

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

The GET call for a Credit Card allows you to retrieve relevant information associated to a particular cardId provided through the following structure:

https://api.sandbox.sovera.io/cards/v2/credit/cards/{CREDIT_CARD_ID}
{
  "success": true,
  "data": {
    "id": "string",
    "userId": "string",
    "walletId": "string",
    "physicalCard": true,
    "code": "string",
    "isActive": true,
    "status": "string",
    "creationDate": "2024-11-12T17:21:18.643Z",
    "dueDate": "string"
  },
  "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 and returns the card's current data.

This call is especially necessary in managing the transaction status of the card, since the successful response also includes the "isActive" boolean activity and the descriptive "status" field, in addition to the other fields in the successful response of card creation.In case an invalid cardId is sent, the Sovera API will respond with an HTTP 404 error.

If there is a HTTP 500 error encountered, report the incident to the Sovera support team.

Not found. An unknown cardId returns HTTP 404:

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

PayIns, PayOuts and Transfers

Move money: PayIns to top up, PayOuts to debit, transfers between wallets.

Card Lifecycle and PIN

Lifecycle and security ops: block, unblock, cancel, check PAN/CVV/PIN, change PIN.

On this page

Create Debit CardRetrieve Debit CardCreate Prepaid CardRetrieve Prepaid CardCreate Credit CardRetrieve Credit Card