Wallet Management API

Buckets

GetWalletBuckets

Gets all Buckets associated to the given Wallet

Request

GET /buckets/{walletId}

Parameters

Name	Type	Default	Notes
*walletId			Gets all Buckets associated to the given Wallet

Responses

Status Code	Type	Description	Samples
200	BucketResponse[]	Returns list of Buckets of the Wallet
400	ErrorModel	Bad Request
403	ErrorModel	Access to another Partner's Wallet is forbidden
404		Wallet cannot be found
422	ErrorModel	Unprocessable Content

ResyncBuckets

Resyncs every Partner's Bucket for each Wallet with at least one deposit

Request

PUT /buckets/{walletId}/resync

Parameters

Name	Type	Default	Notes
*walletId			Resyncs every Partner's Bucket for each Wallet with at least one deposit

Responses

Status Code	Type	Description	Samples
200	ResyncBucketsResponse	Buckets resync successful
400	ErrorModel	Bad Request
403	ErrorModel	Forbidden
422	ErrorModel	Unprocessable Content

Diagnostics

GetDiagnosticsInfo

Get current platform diagnostics data

Request

GET /diagnostics/info

Responses

Status Code	Type	Description	Samples
200	DiagnosticsResponse	Diagnostics data
400	ErrorModel	Bad Request
403	ErrorModel	Forbidden
422	ErrorModel	Unprocessable Content

GetFeaturesStatus

Get status of current microservice features

Request

GET /diagnostics/features

Responses

Status Code	Type	Description	Samples
200	FeaturesStatusResponse	Diagnostic and features availability data
400	ErrorModel	Bad Request
403	ErrorModel	Forbidden
422	ErrorModel	Unprocessable Content

Statistics

GetPartnerWalletsStatistics

Get the Partner's wallets aggregated statistics

Request

GET /statistics/wallets

Responses

Status Code	Type	Description	Samples
200	WalletsStatisticsResult	Returns statistics
400	ErrorModel	Bad Request
403	ErrorModel	Forbidden
404		Statistics for the selected partner cannot be found
422	ErrorModel	Unprocessable Content

GetDealerWalletsStatistics

Get the Originating Dealer's wallets aggregated statistics

Request

GET /statistics/wallets/{dealerKey}

Parameters

Name	Type	Default	Notes
*dealerKey			Get the Originating Dealer's wallets aggregated statistics

Responses

Status Code	Type	Description	Samples
200	WalletsStatisticsResult	Returns statistics
400	ErrorModel	Bad Request
403	ErrorModel	Forbidden
404		Dealer or its statistics cannot be found
422	ErrorModel	Unprocessable Content

Wallets

GetWallet

Get wallet data using provided identifier

Request

GET /wallets/{walletId}

Parameters

Name	Type	Default	Notes
*walletId			Wallet identifier

Responses

Status Code	Type	Description	Samples
200	WalletResponse	Returns requested wallet with data
400	ErrorModel	Bad Request
403	ErrorModel	Access to another Partner's Wallet is forbidden
404		Wallet cannot be found
422	ErrorModel	Unprocessable Content

UpdateWallet

Allows updating TaxId and Email of an existing Wallet

Request

PUT /wallets/{walletId}

Parameters

Name	Type	Default	Notes
*walletId			Wallet identifier
*body	UpdateWalletRequest		Request containing new TaxId and Email values

Responses

Status Code	Type	Description	Samples
200	WalletResponse	The updated Wallet
400	ErrorModel	Email already in use, TaxId is either invalid or already associated to a Wallet on this Partner
403	ErrorModel	Access to another Partner's Wallet is forbidden
404		Wallet cannot be found.
422	ErrorModel	Unprocessable Content

GetWalletBalance

Get wallet balance using provided identifier

Request

GET /wallets/{walletId}/balance

Parameters

Name	Type	Default	Notes
*walletId			Wallet identifier

Responses

Status Code	Type	Description	Samples
200	WalletBalanceResponse	Returns requested wallet balance
400	ErrorModel	Bad Request
403	ErrorModel	Access to another Partner's Wallet is forbidden
404		Wallet cannot be found
422	ErrorModel	Unprocessable Content

GetAllWallets

Get all wallets on platform phase and will be removed as soon as the application goes live! ***

Request

GET /wallets[?fromDate&toDate&pageSize&pageNumber]

Parameters

Name	Type	Default	Notes
fromDate			Get all wallets on platform phase and will be removed as soon as the application goes live! ***
toDate			Get all wallets on platform phase and will be removed as soon as the application goes live! ***
pageSize		50	Get all wallets on platform phase and will be removed as soon as the application goes live! ***
pageNumber		0	Get all wallets on platform phase and will be removed as soon as the application goes live! ***

Responses

Status Code	Type	Description	Samples
200	WalletResponsePaginatedDataResponse	Returns list of wallets on platform
400	ErrorModel	The given pageSize or pageNumber is out of valid range or dates are invalid
403	ErrorModel	Forbidden
422	ErrorModel	Unprocessable Content

CreateWallet

Creates a new wallet on platform

Request

POST /wallets

Parameters

Name	Type	Default	Notes
*body	CreateWalletRequest		Request for creation

Responses

Status Code	Type	Description	Samples
200	WalletResponse	The created Wallet
400	ErrorModel	Email already in use, TaxId is either invalid or already associated to a Wallet on this Partner
403	ErrorModel	Forbidden
422	ErrorModel	Unprocessable Content

GetSctInstructions

Gets the instructions to send an SCT in order to recharge the wallet

Request

GET /wallets/{walletId}/sct/instructions

Parameters

Name	Type	Default	Notes
*walletId			Gets the instructions to send an SCT in order to recharge the wallet

Responses

Status Code	Type	Description	Samples
200	WalletSctInstructionsResponse	The instructions if the IBAN is set
400	ErrorModel	IBAN is not set for the given wallet
403	ErrorModel	Access to another Partner is forbidden
404		Either the wallet or the instructions cannot be found
422	ErrorModel	Unprocessable Content

UpdateWalletAttributes

Allows updating FirstName, LastName and PhoneNumber of an existing Wallet

Request

PUT /wallets/{walletId}/attributes

Parameters

Name	Type	Default	Notes
*walletId			Wallet identifier
*body	UpdateWalletAttributesRequest		Request containing new FirstName, LastName, PhoneNumber and optional Residence values

Responses

Status Code	Type	Description	Samples
200	WalletResponse	The updated Wallet
400	ErrorModel	First and Last name do not match the TaxId
403	ErrorModel	Access to another Partner's Wallet is forbidden
404		Wallet cannot be found.
422	ErrorModel	Unprocessable Content

UpdateWalletIban

Sets the given IBAN to be verified and then associated to the Wallet

Request

PUT /wallets/{walletId}/iban

Parameters

Name	Type	Default	Notes
*walletId			Wallet identifier
*body	UpdateWalletIbanRequest		Request containing the IBAN and BIC to associate to the Wallet

Responses

Status Code	Type	Description	Samples
200	UpdateWalletIbanResponse	The updated Wallet
400	ErrorModel	IBAN already associated to a Wallet
403	ErrorModel	Access to another Partner's Wallet is forbidden
404		Wallet cannot be found
422	ErrorModel	Unprocessable Content

DeleteWalletIban

Removes the associated IBAN from the given Wallet, regardless of the validation state

Request

DELETE /wallets/{walletId}/iban

Parameters

Name	Type	Default	Notes
*walletId			Wallet identifier

Responses

Status Code	Type	Description	Samples
200	WalletResponse	The updated Wallet
400	ErrorModel	No IBAN is associated to the Wallet
403	ErrorModel	Access to another Partner's Wallet is forbidden
404		Wallet cannot be found
422	ErrorModel	Unprocessable Content

SuspendWallet

Suspend an existing wallet using its identifier. Suspension deny to the end user the usage of his wallet for any operation (deposit, payment, withdrawal, etc).

Request

PUT /wallets/{walletId}/suspend

Parameters

Name	Type	Default	Notes
*walletId			Wallet identifier

Responses

Status Code	Type	Description	Samples
200	WalletResponse	Returns suspended wallet
400	ErrorModel	Wallet is not in active status
403	ErrorModel	Access to another dealer's wallet is forbidden
404		Wallet cannot be found.
422	ErrorModel	Unprocessable Content

ReactivateWallet

Reactivates an existing suspended wallet using its identifier.

Request

PUT /wallets/{walletId}/reactivate

Parameters

Name	Type	Default	Notes
*walletId			Wallet identifier

Responses

Status Code	Type	Description	Samples
200	WalletResponse	Returns reactivated wallet
400	ErrorModel	Wallet is not in suspended status
403	ErrorModel	Access to another dealer's wallet is forbidden
404		Wallet cannot be found.
422	ErrorModel	Unprocessable Content

CloseWallet

Close an existing suspended wallet using its identifier.

Request

PUT /wallets/{walletId}/close

Parameters

Name	Type	Default	Notes
*walletId			Wallet identifier

Responses

Status Code	Type	Description	Samples
200	WalletResponse	Returns closed wallet
400	ErrorModel	Wallet is not in suspended status
403	ErrorModel	Access to another dealer's wallet is forbidden
404		Wallet cannot be found.
422	ErrorModel	Unprocessable Content

SearchWallet

Searches for existing Wallets matching each given parameter.

NOTE: Ignores missing, null, empty of white space only search parameters

Request

POST /wallets/search[?pageSize&pageNumber]

Parameters

Name	Type	Default	Notes
pageSize		50	Number of wallets per page
pageNumber		0	Page number
*body	SearchWalletsRequest		Request containing search fields

Responses

Status Code	Type	Description	Samples
200	WalletResponsePaginatedDataResponse	The paginated list of Wallets matching all search parameters ordered by creation date
400	ErrorModel	One or more search parameter is invalid
403	ErrorModel	Forbidden
422	ErrorModel	Unprocessable Content

GetWalletLimits

Get wallet limit using provided identifier

Request

GET /wallets/{walletId}/limits

Parameters

Name	Type	Default	Notes
*walletId			Wallet identifier

Responses

Status Code	Type	Description	Samples
200	WalletLimitsResponse	Returns requested wallet limits
400	ErrorModel	Bad Request
403	ErrorModel	Access to another Partner's Wallet is forbidden
404		Wallet cannot be found
422	ErrorModel	Unprocessable Content

DestroyWallet

*** ATTENTION: THIS ENDPOINT IS AVALIABLE ONLY IN TESTING AND DEVELOPMENT ENVIRONMENTS *** Deletes a Closed Wallet alongside any associated Operation, Group, SDD mandate and Transaction.

Request

DELETE /wallets/{walletId}/force

Parameters

Name	Type	Default	Notes
*walletId			Wallet identifier

Responses

Status Code	Type	Description	Samples
200		Deletion successful
400	ErrorModel	Wallet is not Closed
403	ErrorModel	Access to another Partner's Wallet is forbidden
404		Wallet cannot be found
422	ErrorModel	Unprocessable Content

Definitions

BucketResponse

Name	Type	Notes
bucketId	string (uuid)	Bucket unique identifier
walletId	string (uuid)	Unique identifier of the owning Wallet
partnerKey	string	Partner key
availableBalance	number (double)	Available balance on the Bucket
creationDate	string (date-time)	Creation date
lastIncomingDate	string (date-time)	Date of last incoming amount (i.e. IN Operations) to the Bucket
lastOutgoingDate	string (date-time)	Date of last outgoing amount (i.e. OUT Operations) to the Bucket
isWithdrawable	boolean	Marks if the balance of the Bucket can be Withdrawn

ErrorModel

Name	Type	Notes
errorCode	string
errorDescription	string
errorProperties	object

ResyncBucketsResponse

Resync Buckets response

Name	Type	Notes
createdBuckets	integer (int32)	Number of buckets created
updatedBuckets	integer (int32)	Number of buckets updated

DiagnosticsResponse

Response for platform diagnostics

Name	Type	Notes
applicationName	string	Application name
applicationVersion	string	Application version
environment	string	Environment name

FeaturesStatusResponse

Name	Type	Notes
serviceData	DiagnosticsResponse[]	Service diagnostic details
featuresStatus	FeatureAvailability[]	Status of all service features

FeatureAvailability

Status of all service features

Name	Type	Notes
name	string
isAvailable	boolean

WalletsStatisticsResult

Result containing wallets statistics for the selected partner

Name	Type	Notes
walletsCount	integer (int32)	Count of all wallets
walletsOpen	integer (int32)	Count of only open/active wallets
walletsSuspended	integer (int32)	Count of only suspended wallets
walletsClosed	integer (int32)	Count of only closed wallets
walletsIbanValidated	integer (int32)	Count of wallets with IBAN validated (excluded closed wallets)
walletsPendingIbanValidation	integer (int32)	Count of wallets pending IBAN validation (excluded closed wallets)
walletsWithoutIban	integer (int32)	Count of wallets without IBAN set (excluded closed wallets)
walletsTotalAvailableBalance	number (double)	Sum of all available balances
walletsEarliestCreationDate	string (date-time)	Date of the earliest wallet created
walletsLatestCreationDate	string (date-time)	Date if the latest wallet created
walletsEarliestUsageDate	string (date-time)	Date of the earliest usage of a wallet
walletsLatestUsageDate	string (date-time)	Date of the latest usage of a wallet
walletsEarliestUpdateDate	string (date-time)	Date of the earliest update of a wallet
walletsLatestUpdateDate	string (date-time)	Date of the latest update of a wallet

WalletResponse

Wallet response

Name	Type	Notes
walletId	string (uuid)	Wallet unique identifier
partnerKey	string	Partner key
taxId	string	Owner tax identifier
firstName	string	Owner first name
lastName	string	Owner last name
iban	string	IBAN
bic	string	BIC associated to the IBAN (needed only if IBAN is not Italian)
isIbanValidated	boolean	Flag to mark that the user's IBAN has been verified
ibanValidationCode	string	Code used for IBAN validation, it must match the first SCT reason
phoneNumber	string	Owner phone number
email	string	Owner e-mail
creationDate	string (date-time)	Creation date
lastUpdateDate	string (date-time)	Date of last update of wallet data
lastUsageDate	string (date-time)	Date of last usage of wallet for any operation (deposit, payment, etc)
closureDate	string (date-time)	Date of closure of wallet
suspensionDate	string (date-time)	Date of suspension of wallet
originatingDealerKey	string	Original dealer for which the wallet was created
addressStreet	string	Street of residence
addressNumber	string	Street number
zipCode	string	City postal code
city	string	City of residence
province	string	Province of residence
country	string	Country of residence

UpdateWalletRequest

Request for updating single wallet core data

Name	Type	Notes
taxId	string	Owner TaxId
email	string	Owner Email

WalletBalanceResponse

Waller balance response

Name	Type	Notes
availableBalance	number (double)	Available balance on wallet;

WalletResponsePaginatedDataResponse

Name	Type	Notes
totalCount	integer (int32)
items	WalletResponse[]

CreateWalletRequest

Request for create a new wallet

Name	Type	Notes
taxId	string	Owner tax identifier
firstName	string	Owner first name
lastName	string	Owner last name
phoneNumber	string	Owner phone number
email	string	Owner e-mail
originatingDealerKey	string	Original dealer for which the wallet was created

WalletSctInstructionsResponse

Name	Type	Notes
walletId	string (uuid)	Wallet unique identifier
partnerKey	string	Partner key
destinationOwner	string	Name associated to the destination IBAN
destinationIban	string	IBAN of the partner
reason	string	Reason to use for the SCT
amountFirstDeposit	number (double)	Contains the value for the first deposit if the IBAN is yet to be validated

UpdateWalletAttributesRequest

Request for updating single wallet attributes

Name	Type	Notes
firstName	string	Owner first name
lastName	string	Owner last name
phoneNumber	string	Owner phone number
addressStreet	string	Street of residence
addressNumber	string	Street number
zipCode	string	City postal code
city	string	City of residence
province	string	Province of residence
country	string	Country of residence

UpdateWalletIbanRequest

Request for updating a wallet's IBAN

Name	Type	Notes
iban	string	Owner IBAN
bic	string	BIC associated to the IBAN (needed only if IBAN is not Italian)

UpdateWalletIbanResponse

Response of wallet IBAN update

Name	Type	Notes
walletId	string (uuid)	Wallet unique identifier
partnerKey	string	Partner key
iban	string	IBAN of the Wallet to be verified
bic	string	BIC associated to the IBAN (needed only if IBAN is not Italian)
isIbanValidated	boolean	Flag to mark that the user's IBAN has been verified
destinationIban	string	IBAN to which the transfer must be made for verification
destinationOwner	string	Name associated to the destination IBAN
transferAmount	number (double)	Amount to transfer for IBAN verification
ibanValidationCode	string	Code used for IBAN validation, it must match the first SCT reason

SearchWalletsRequest

Request to search wallets using their values

Name	Type	Notes
taxId	string	Owner tax identifier: exact match, case insensitive
firstName	string	Owner first name: partial match (contains), case insensitive
lastName	string	Owner last name: partial match (contains), case insensitive
phoneNumber	string	Owner phone number: partial match (contains), case insensitive
email	string	Owner e-mail: partial match (contains), case insensitive
iban	string	IBAN of wallet owner: exact match, case insensitive
isSuspended	boolean	If wallet is suspended (if null searches for both suspended and not suspended ones) NOTE: cannot be false if IsClosed is true
isClosed	boolean	If wallet is closed (if null searches for both closed and open ones)
hasNeverBeenUsed	boolean	Searches only for Wallets that never executed any Operation (LastUsageDate never set)

WalletLimitsResponse

Response with current limits for wallet

Name	Type	Notes
maximum	WalletSingleLimitsResponse[]	Maximum limit for wallet (ex. 1000€)
minimum	WalletSingleLimitsResponse[]	Minumum limit for wallet (ex. 0€)
maximumLastMonthCashDeposit	WalletSingleLimitsResponse[]	Maximum limit for cash deposit on last month
maximumLastMonthCashWithdrawal	WalletSingleLimitsResponse[]	Maximum limit for cash withdrawal on last month

WalletSingleLimitsResponse

Maximum limit for wallet (ex. 1000€)

Name	Type	Notes
limit	number (double)	Limit amount
current	number (double)	Current balance
remainingAmountToLimit	number (double)	Remaining amount before reach limit
exceedAmountFromLimit	number (double)	Exceeded amount beyond limit
violationMessage	string	Message for violation of limit (only if limit is violated)