Business - Wallets

The Admin interface handles web service calls from the Admin web gui. The base url for this is at:

/api/business-admin

A JSON file with OpenAPI data about all business-related admin APIs can be downloaded here.

Get wallet data

Gets details about a specific wallet:

GET /v1/wallets/{id}

Gets details about a specific wallet

Parameters

id (integer) – The wallet to retrieve data for

Status Codes

200 OK – Success

id: Wallet ID (int)

Returns a plain Json negative message if there was a problem retrieving the detail or a Json positive response with the requested details:

{
  ID: 1234,                               // Int
  CreatedDate: "2001-01-01T01:01:01Z",    // DateTime
  LastUsed: "2021-01-01T01:01:01Z",       // DateTime (nullable)
  TokenBalance: 1,                        // Int
  MinutesBalance: 0,                      // Decimal
  KmBalance: 10                           // Decimal
}

Values of the BalanceUnit property can be one of the BalanceUnit enumeration.

Get wallet movements

Gets the movement’s paged list for a specified wallet

GET /v1/wallets/{id}/movements

Gets the list of movements for a specific wallet

Parameters

id (integer) – The wallet id

Query Parameters

filteredTypes (string) – An optional list of movement types to be filtered as integers divided by comma
filteredUnit (integer) – An optional integer specifying a balance unit to be filtered

Status Codes

200 OK – Success

id: Wallet ID (int)

The API accepts the following filters in the query params: * filteredTypes (comma separated list of movement types, as int value, to be extracted) * filteredUnit (single balance unit, as int value, to be extracted)

Returns a Json positive response with the list of movements limited by the page settings:

[
  {
    ID: 5,
    CreatedDate: "2001-01-01T01:00:00Z",
    BalanceUnit: 0,
    MovementType: 0,
    ExecutingUser: "user@test.com",
    TotalAmount: 10,
    Notes: "Some notes"
  },
  { ... }
]

where BalanceUnit and MovementType can be one of the BalanceUnit and MovementType enumeration respectively

Possible errors are:

err_InvalidElement: One of the provided filteredTypes or the provided filteredUnit does not map to any accepted value

Refill or consume wallet amount

The two APIs allows an operator to add or remove a specified amount of balance unit to/from a wallet

POST /v1/wallets/{id}/top-up

Top ups a balance unit of a wallet with a specified amount

Parameters

id (integer) –

Status Codes

200 OK – Success

POST /v1/wallets/{id}/consume

Consumes a balance unit of a wallet by a specified amount

Parameters

id (integer) –

Status Codes

200 OK – Success

id: Wallet ID (int)

The two APIs accept a request body in the following format:

{
  BalanceUnit: 1,         // Int
  Amount: 10,             // Decimal
  Notes: "some string"    // String (nullable)
}

where BalanceUnit can be one of the value defined in the BalanceUnit enumeration.

The top-up call will add the specified balance unit amount to the wallet, while the consume API will remove the specified unit amount.

Possible errors are:

err_NoWalletFound: no wallet has been found for the specified id
err_InvalidElement: the provided balance unit does not map to any allowed value, or the provided amount is less than the accepted value (less than one for tokens, zero or negative for distance and minutes)
err_MaxAmountReached: returned from the top-up API when the specified amount, if added to the wallet, will have it exceed the maximum amount as specified in the related environment variable
err_WalletAmountNegative: returned from the consume API when the wallet already has a zero or negative amount for the specified balance unit

Transfer unit from a wallet to another

Allows to transfert a specified amount of a balance unit from a wallet to another

POST /v1/wallets/transfer

Transfers a specified amount from one wallet to another

Status Codes

200 OK – Success

The API accepts a request body in the following format:

{
  SourceID: 1,           // Int, ID of the source wallet
  DestinationID: 2,      // Int, ID of the destination wallet
  BalanceUnit: 0,        // Int
  TransferAmount: 10,    // Decimal
  Notes: "some notes"    // String (nullable)
}

where BalanceUnit can be one of the value defined in the BalanceUnit enumeration.

The API will transfer the specified amount from the source wallet to the destination. The operation will also register a specific action log.

Possible errors are:

err_NoSourceWalletFound: no SourceID was specified, or no wallet maps to the specified id
err_NoDestinationWalletFound: no DestinationID was specified, or no wallet maps to the specified id
err_SourceEqualToDestination: the provided SourceID and DestinationID maps to the same wallet
err_InvalidElement: the provided balance unit does not map to any allowed value, or the provided amount is less than the accepted value (less than one for tokens, zero or negative for distance and minutes)
err_NotEnoughSourceBalance: the provided unit amount to be transferred exceeds the current capability of the source wallet
err_MaxDestinationAmountReached: adding the specified unit amount to the destination wallet will have it exceed the maximum allowd amount, as specified in the related environment variable

Transfer full wallet content to another wallet

Allows to transfer the full content of a wallet to another wallet

POST /v1/wallets/transfer-all

Transfers all balance units from one wallet to another

Status Codes

200 OK – Success

The API accepts a request body in the following format:

{
  SourceID: 1,           // Int, ID of the source wallet
  DestinationID: 2,      // Int, ID of the destination wallet
  Notes: "some notes"    // String (nullable)
}

The API will transfer the full contento of the specified source wallet to the destination. The operation will also register a specific action log.

err_NoSourceWalletFound: no SourceID was specified, or no wallet maps to the specified id
err_NoDestinationWalletFound: no DestinationID was specified, or no wallet maps to the specified id
err_SourceEqualToDestination: the provided SourceID and DestinationID maps to the same wallet
err_SourceAmountNegative: the provided SourceID has one or more unit content negative
err_SourceAmountZero: all the unit content of the provided SourceID is zero
err_MaxDestinationAmountReached: adding the specified unit amount to the destination wallet will have it exceed the maximum allowd amount, as specified in the related environment variable