Wallet Operations


Contents



Introduction


Once you create a user, a wallet is automatically created and associated to their user's ID. Throughout these docs you will learn all the actions you can do with the wallets of the users.



Operations


Get wallet info


You can get the information of a wallet by using the id of the wallet or by using the id of the user that owns it. You can do so by using the following requests:


HTTP Request


GET /api/v1/public/wallets/{walletId} where the parameter walletId in our example would be: cd496094-a77a-4e4e-bcd9-3361ff89294a. Therefore, the request would look like this: /api/v1/public/wallets/cd496094-a77a-4e4e-bcd9-3361ff89294a

GET /api/v1/public/wallets?userId="XXX" where the parameter userId is the user's ID from which you want to get the associated wallet info. This request will return all the wallets that the user owns in the system. In our example, using the user ID, the whole request would look like this: /api/v1/public/wallets?userId=91af1cb8-1caa-47d0-8ef8-2c11948baaba.


HTTP Response


As response, you will get all the information of that wallet. If the user had more than one wallet, they would all appear. In our example it would look like this:


{
  "_links": {
    "self": {
      "href": "/api/v1/public/wallets?page=0&size=20&sort=createdAt,asc"
    },
    "first": {
      "href": "/api/v1/public/wallets?page=0&size=20&sort=createdAt,asc"
    },
    "last": {
      "href": "/api/v1/public/wallets?page=0&size=20&sort=createdAt,asc"
    }
  },
  "_embedded": {
    "wallets": [
      {
        "id": "cd496094-a77a-4e4e-bcd9-3361ff89294a",
        "availableBalance": 1002.32,
        "balance": 1000.32,
        "heldBalance": 2.0,
        "clientAlias": "alias_test",
        "clientId": "f34ed6d7-6703-4486-b591-23ee8f20d8b4",
        "dltAddress": "0x95066cdf6a5ac9489eeb28755f0e878eb3de711d",
        "iban": "ES7002320521100021450612",
        "status": "READY",
        "userId": "91af1cb8-1caa-47d0-8ef8-2c11948baaba"
      }
    ]
  }
}


Where:


HTTP Response parameters


Parameter Datatype Description
id string UUID of the wallet
availableBalance numeric Balance with which the user can operate
balance numeric Total balance of the wallet without taking into account pending operations
heldBalance numeric Balance that is on hold and unavailable for the user due to pending operations or escrows
clientAlias string Name of the client as it is saved in the system
clientId string The UUID of the client which was used to create the user
dltAddress string DLT address associated to the wallet
iban string IBAN number associated to the wallet. Available in KYC1 or higher
status string The status can be either READY or PENDING
userId string The UUID of the user introduced and that owns the wallet

Note that the status of the wallet in the JSON example is READY and therefore it can be used for any payment or funding operation.




Get wallets list


If you want to get the list of all the wallets that exist in your system make the following request:


HTTP Request


GET /api/v1/public/wallets

As a response, you will get a JSON array with the information of all the wallets in your system.

The call can be paged. This is specially usefull when you have to retrieve a big amount of elements.

By default, the size of the page is 20 elements, and you can put a maximum size of 2000 elements. The response shows a list of resources to make the paged calls, basically you can set the page, the size, and the field you want to sort the list by.

Example:

GET api/v1/public/wallets?page=0&size=25&sort=createdAt,asc

If you want to try any of these functionalities yourself, please go to the API catalogue.



Create an extra wallet


If your use case needs it, you can create extra wallets for your users. Note, that to be able to create an extra wallet for a user, this one has to be in status ACTIVATED. Right now, we have limited the number of wallets per user to 5. This can be extended if your specific use case requires it.

For creating an extra wallet, you have to make the following request:


HTTP Request

POST /api/v1/public/wallets


With the following information provided as JSON:


{
  "dltAddress": "0x485De9F4580eDEDB5b16a84028e4Bac64434c36D",
  "userId": "a5fec227-17cf-4be8-b2aa-b514e38e2b29"
}

Request body parameters


Parameter Mandatory Datatype Description
dltAddress no string The Ethereum address of the new wallet.
The client can either use an already existing address, if the user provides it, or create a new one.
This field is optional for use cases that do not want to enable the possibility to directly operate against the dlt, if empty, the system will automatically create a wallet discarding the private key.
userId yes string The UUID of the user that is creating the new wallet

As response, you will get the following JSON object:


{
  "_links": {
    "self": {
      "href": "/api/v1/public/wallets/c86db278-6eb4-4af2-b023-753eba091d1c"
    }
  },
  "dltAddress": "0x485De9F4580eDEDB5b16a84028e4Bac64434c36D"
  "dltNetwork": "Alastria Telsius",
  "status": "READY",
  "userId": "91af1cb8-1caa-47d0-8ef8-2c11948baaba",
  "walletId": "c86db278-6eb4-4af2-b023-753eba091d1c"
}

Where:

HTTP Response parameters


Parameter Datatype Description
dltAddress string The value which was provided in the request
dltNetwork string Default network of the client where the wallet is created and in which it will be operating.
status string The status can be either PENDING_IBAN or READY.
userId string The value which was provided in the request
walletId string The UUID generated for the created wallet

Create iban for wallet


If your use case needs it, you can create an iban for your users' wallets. Note, that to be able to create an iban for a wallet, this one has to be in status READY and its user cannot be in status UNSUBSCRIBED. In addition, the user has to be in KYC level 1 or higher. The request you have to make is the following:


HTTP Request

POST /api/v1/public/wallets/{walletId}/create-iban where the parameter walletId in our example would be: cd496094-a77a-4e4e-bcd9-3361ff89294a. Therefore, the whole request would look like this: /api/v1/public/wallets/cd496094-a77a-4e4e-bcd9-3361ff89294a/create-iban



As response, you will get the following JSON object:


{
  "_links": {
    "self": {
      "href": "/api/v1/public/wallets/c86db278-6eb4-4af2-b023-753eba091d1c"
    }
  },
  "iban": "ES2101827295711688143168"
}

Where:

HTTP Response parameters


Parameter Datatype Description
iban string The new IBAN generated for the wallet

Unsubscribe wallet


If your use case needs it, you can unsubscribe wallets for your users. This action is irreversible, i.e. the user will not be able to use the wallet again for any operation. In addition, It will not be possible to create a wallet with the same DLT address as the one of the unsubscribed wallet.

In order to unsubscribe a wallet, the API will check the following:

  1. The user that owns the wallet is only linked to one client.
  2. The wallet to be unsubscribed has total balance, available balance and held balance equal to 0

HTTP Request

DELETE /api/v1/public/wallets/{walletId} where the parameter id stands for the id of the wallet.


As response, you will get the following JSON object:


{
  "_links": {
    "self": {
      "href": "/api/v1/public/wallets/c86db278-6eb4-4af2-b023-753eba091d1c"
    }
  },
  "dltAddress": "0x485De9F4580eDEDB5b16a84028e4Bac64434c36D"
  "dltNetwork": "Alastria Telsius",
  "status": "UNSUBSCRIBED",
  "userId": "91af1cb8-1caa-47d0-8ef8-2c11948baaba",
  "walletId": "c86db278-6eb4-4af2-b023-753eba091d1c"
}

Where:

HTTP Response parameters


Parameter Datatype Description
dltAddress string The dltAddress that had the wallet unsubscribed
dltNetwork string The dltANetwork that the unsubscribed wallet belonged to
status string The status of the wallet
userId string The id of the user that the wallet belonged to
walletId string The wallet id value which was provided in the request to be unsunbscribed

Add favourite external account


If your users need it, you can add favourite external accounts for their walletw and then perform operations with these favourites without informing again the account data. Note, that to be able to add a favourite external account for a wallet, this one has to be in status READY. Right now, we have limited the number of favourite external accounts per wallet to 5. This can be extended if your specific use case requires it.

For adding a favourite external account, you have to make the following request:


HTTP Request

POST /api/v1/public/wallets/{walletId}/favourite-external-accounts


With the following information provided as JSON:


{
  "alias": "My favourite account",
  "externalIban": {
    "accountNumber": "ES0221004440760100171757"
  }
}

Request body parameters


Parameter Mandatory Datatype Description
alias yes string The alias of the favourite external account.
The alias must be unique per wallet.
externalIban yes Object EXTERNAL IBAN object

EXTERNAL IBAN object


Parameter Required Datatype Description
accountNumber yes string The IBAN of the external bank account


As response, you will get the following JSON object:


{
  "_links": {
    "self": {
      "href": "/api/v1/public/wallets/c86db278-6eb4-4af2-b023-753eba091d1c/favourite-external-accounts"
    }
  },
  "favouriteExternalAccountId": "91af1cb8-1caa-47d0-8ef8-2c11948baaba",
  "alias": "My favourite account",
  "externalIban": "ES0221004440760100171757",
  "status": "ACTIVE"
}

Where:

HTTP Response parameters


Parameter Datatype Description
favouriteExternalAccountId UUID The id of the favourite external account
alias string Alias that represents the favourite external account.
externalIban string External account number
status string Favourite external account status can be either ACTIVE or DELETED.

Get favourite external account


If you want to access to the information of a favourite external account of a specific wallet you have to send the following request:


HTTP Request


GET /api/v1/public/wallets/{walletId}/favourite-external-accounts/{favouriteExternalAccountId} where the parameter walletId in our example would be: cd496094-a77a-4e4e-bcd9-3361ff89294a and the favouriteExternalAccountId can be for example a5fec227-17cf-4be8-b2aa-b514e38e2b29. Therefore, the whole request would look like this: /api/v1/public/wallets/cd496094-a77a-4e4e-bcd9-3361ff89294a/favourite-external-accounts/a5fec227-17cf-4be8-b2aa-b514e38e2b29.


HTTP Response


As response, you will get a JSON with all the information of that favourite external account.


{
  "_links": {
    "wallet": {
      "href": "/api/v1/public/wallets/cd496094-a77a-4e4e-bcd9-3361ff89294a"
    },
    "self": {
      "href": "/api/v1/public/wallets/c86db278-6eb4-4af2-b023-753eba091d1c/favourite-external-accounts/a5fec227-17cf-4be8-b2aa-b514e38e2b29"
    }
  },
  "alias": "My favourite account",
  "iban": "ES3320801248101464337536",
  "id": "a5fec227-17cf-4be8-b2aa-b514e38e2b29",
  "status": "ACTIVE",
  "walletId": "cd496094-a77a-4e4e-bcd9-3361ff89294a"
}


Where:


HTTP Response parameters


Parameter Datatype Description
alias string Alias that represents the favourite external account.
iban string External account number
id UUID The id of the deleted favourite external account
status string Favourite external account status can be either ACTIVE or DELETED.
walletId UUID The id of the wallet


Get favourite external accounts list


If you want to get the list of all the favourite external accounts of a specific wallet make the following request:


HTTP Request


GET /api/v1/public/wallets/{walletId}/favourite-external-accounts

As a response, you will get a JSON array with the information of all the favourite external accounts of that wallet.

The call can be paged. This is specially usefull when you have to retrieve a big amount of elements.

By default, the size of the page is 20 elements, and you can put a maximum size of 2000 elements. The response shows a list of resources to make the paged calls, basically you can set the page, the size, and the field you want to sort the list by.

Example:

GET api/v2/public/wallets/{walletId}/favourite-external-accounts?page=0&size=25&sort=createdAt,asc.

If you want to try any of these functionalities yourself and know more about them, please go to the API catalogue.



Delete favourite external account


You can delete favourite external accounts for your wallets. This action is irreversible, i.e. the user will not be able to use the favourite external account again for any operation. But you can add a new favourite external account with the same data.

In order to delete a favaourite external account, you have to make the following request:


HTTP Request

DELETE /api/v1/public/wallets/{walletId}/favourite-external-accounts/{favouriteExternalAccountId}


As response, you will get the following JSON object:


{
  "_links": {
    "self": {
      "href": "/api/v1/public/wallets/c86db278-6eb4-4af2-b023-753eba091d1c/favourite-external-accounts"
    }
  },
  "favouriteExternalAccountId": "91af1cb8-1caa-47d0-8ef8-2c11948baaba",
  "alias": "My favourite account",
  "externalIban": "ES0221004440760100171757",
  "status": "DELETED"
}

Where:

HTTP Response parameters


Parameter Datatype Description
favouriteExternalAccountId UUID The id of the deleted favourite external account
alias string Alias that represents the deletedfavourite external account.
externalIban string External account number
status string Favourite external account status can be either ACTIVE or DELETED.

Get movement info


If you want to access to the information of a movement of a specific wallet you have to send the following request:


HTTP Request


GET /api/v1/public/wallets/{walletId}/movements/{movementId} where the parameter walletId in our example would be: cd496094-a77a-4e4e-bcd9-3361ff89294a and the movementID can be for example a5fec227-17cf-4be8-b2aa-b514e38e2b29. Therefore, the whole request would look like this: /api/v1/public/wallets/cd496094-a77a-4e4e-bcd9-3361ff89294a/movements/a5fec227-17cf-4be8-b2aa-b514e38e2b29.


HTTP Response


As response, you will get a JSON with all the information of that movement. Below, it is shown a movement of a transfer-in in which the wallet requested made a transaction to another wallet with an amount of 10.


{
  "_links": {
    "originUser": {
      "href": "/api/v1/public/users/cd496094-a77a-4e4e-bcd9-3361ff89294a"
    },
    "targetUser": {
      "href": "/api/v1/public/users/2c36f452-2ea4-4448-962b-365cdb5ae027"
    },
    "originWallet": {
      "href": "/api/v1/public/wallets/02561361-e5a6-4282-8824-a2933eab4d8e"
    },
    "targetWallet": {
      "href": "/api/v1/public/wallets/465107e1-9cb7-4e72-9c75-3989ec37e26e"
    },
    "self": {
      "href": "/api/v1/public/wallets/465107e1-9cb7-4e72-9c75-3989ec37e26e/movements/a5fec227-17cf-4be8-b2aa-b514e38e2b29"
    }
  },
  "id": "a5fec227-17cf-4be8-b2aa-b514e38e2b29",
  “originUserId": "cd496094-a77a-4e4e-bcd9-3361ff89294a",
  “targetUserId": "2c36f452-2ea4-4448-962b-365cdb5ae027"
  "amount": 10,
  "clientId": "6f075cab-638e-4e24-95d6-603e72f94056",
  "concept": "cash-in from my credit card",
  "createdAt": "2018-11-28T10:21:20.198+0000",
  “originDltAddress": "0x95066cdf6a5ac9489eeb28755f0e878eb3de711d",
  “targetDltAddress": "0xd6341daf46ecb065b00c0baebc098ae06ed01c90",
  “originWalletId”: “02561361-e5a6-4282-8824-a2933eab4d8e”,
  “targetWalletId”: “465107e1-9cb7-4e72-9c75-3989ec37e26e”,
  "dltNetwork": "AlastriaTelsius",
  "status": "SUCCESS",
  "type": "TRANSFER_IN",
  "updatedAt": "2018-11-28T10:21:21.966+0000",
  "scheduledOperationId": "8ee441a6-b104-4a29-b3a5-909597468a20"
}


Where:


HTTP Response parameters


Parameter Datatype Description
id string UUID of the movement
originUserId string ID of the sender's wallet if the movement type is TRANSFER_IN or TRANSFER_OUT. Empty if the movement type is any other
targetUserId string ID of the receiver's wallet if the movement type is TRANSFER_IN or TRANSFER_OUT. Empty if the movement type is any other
userId string User id associated to the movement if the movement type is different from TRANSFER_IN or TRANSFER_OUT
payerName string Payer’s name when movement type is BANK_ACCOUNT_CASH_OUT. Empty if the movement type is any other
amount numeric Amount of money moved
clientId string UUID of the client
concept string Description with the purpose of the movement
createdAt string Timestamp of the movement creation
originDltAddress string DLT address associated to the sender's wallet if the movement type is TRANSFER_IN or TRANSFER_OUT. Empty if the movement type is any other
targetDltAddress string DLT address associated to the receiver's wallet if the movement type is TRANSFER_IN or TRANSFER_OUT. Empty if the movement type is any other
originWalletId string Wallet id associated to the sender's wallet if the movement type is TRANSFER_IN or TRANSFER_OUT. Empty if the movement type is any other
targetWalletId string Wallet id associated to the receiver's wallet if the movement type is TRANSFER_IN or TRANSFER_OUT. Empty if the movement type is any other
walletId string Wallet id associated to the movement if the movement type is different from TRANSFER_IN or TRANSFER_OUT
dltNetwork string Blockchain network in which the transaction is done
status string The status can be either SUCCESS, PENDING or ERROR
type string The type of movement can be either CARD_CASHIN, BANK_ACCOUNT_CASHIN, BANK_ACCOUNT_CASHOUT, TRANSFER_IN, TRANSFER_OUT, LOCK or RELEASE
updatedAt string Timestamp of the movement update
scheduledOperationId string Scheduled operation UUID id string related to the movement. Only filled if the movement is related to an scheduled operation.

Note: When a transfer is made between two accounts, there are two movements generated: one when the money leaves the origin account TRANSFER_OUT and another when it reaches the target account TRANSFER_IN.



Get movements list


If you want to get the list of all the movements of a specific wallet make the following request:


HTTP Request


GET /api/v1/public/wallets/{walletId}/movements

As a response, you will get a JSON array with the information of all the movements of that wallet.

The call can be paged. This is specially usefull when you have to retrieve a big amount of elements.

By default, the size of the page is 20 elements, and you can put a maximum size of 2000 elements. The response shows a list of resources to make the paged calls, basically you can set the page, the size, and the field you want to sort the list by.

Example of pagination:

GET api/v2/public/wallets/{walletId}/movementspage=0&size=25&sort=createdAt,asc

Additionaly, you can filter the list of movements by startDate, endDate and status. By default, there are no filters

Example with filtering:

GET api/v2/public/wallets/{walletId}/movements?startDate=2020-02-28 12:00:00&endDate=2020-02-28 16:00:00&status=SUCCESS&page=0&size=25&sort=createdAt,asc

If you want to try any of these functionalities yourself and know more about them, please go to the API catalogue.



Card Cash-in


In order to fund the user’s wallet you can make a credit or debit card top up with the API. Card data should be encrypted prior to performing cash-in operations using symmetric-key encryption algorithm AES 256 ECB. Our API provides a temporal encryption key to encrypt the data, to get this key you should make the following request:


HTTP Request


POST /api/v1/public/wallets/temporalpk


HTTP Response


As response, you will get the key as shown below:


{
  "_links": {
    "self": {
      "href": "/api/v1/public/wallets/temporalpk"
    }
  },
  "temporalPK": "iOeuSHZgOoO23GKoSMzLhJa+tCzfF1/ZfHL8ByUcDZMfa8QhAKzW1sX/FJj8Ipa5OY6IPVz5tsv3l4IBtAKOaha2y9XsI+0hJ++XacPYeXclHb063iHwxKqN/rQ9S9dV0E9ynvECwxJJv5CPJlVCLuoWoIa7k37BDCSpbwp+HnWiHEe4ni7KtgeXTDo0MEaLjQpeZ+EMqmmzd8EeTVlugfOd258x1P5smJSY6c6u1x3zuBB/Qbs+gguG8wXcaD0WLYCize96ZkML66LZKbe+pP6NQe9mireJi3wNFJT2NXgygJO9dtItlJzLImFAUbluCNdRnkrSQ2HB8us9O/WjEw=="
}

Where:


Parameter Datatype Description
temporalPK string Temporary encryption key encrypted with your public key so that only you can decrypt it

It is recommended to get the temporal private key every time you want to make a cash-in.

To get the AES key for encrypting the data, you should decrypt the temporal key with your RSA asymmetric private key related to the public key you sent us. Here is an example of decrypting the temporal key in Java code: 


KeyFactory kf = KeyFactory.getInstance("RSA");
PKCS8EncodedKeySpec keySpec = new PKCS8EncodedKeySpec(Base64.getDecoder().decode("Base64 encoded private key"));

Cipher cipher = Cipher.getInstance("RSA");
cipher.init(Cipher.DECRYPT_MODE, kf.generatePrivate(keySpec));
return new String(cipher.doFinal(Base64.getDecoder().decode("temporal key")), StandardCharsets.UTF_8);

Once this is done you can use the resulting key to encrypt the user's credit/debit card data using symmetric-key encryption algorithm AES 256 ECB. Fields need to be encoded to Base64 prior to sending them to the API. An example in Java code is shown below: 

// Hex is a class from the Apache Commons Codec library
SecretKeySpec secretKeySpec = new SecretKeySpec(Hex.decodeHex("decrypted temporal key"), "AES");

Cipher cipher = Cipher.getInstance("AES");
cipher.init(Cipher.ENCRYPT_MODE, secretKeySpec);
return Base64.getEncoder().encodeToString(cipher.doFinal("card data field to encrypt".getBytes(StandardCharsets.UTF_8)));

Fields that need to be encrypted are: Owner, number, expiration date in MMYY format and CVV.

Now you can perform a top up by making the following request:


HTTP Request


POST /api/v1/public/wallets/{walletId}/cards/cashIns where the walletId is the UUID of the wallet which will receive the money. In our example, the whole request will be /api/v1/public/wallets/cd496094-a77a-4e4e-bcd9-3361ff89294a/cards/cashIns

An example of the JSON with an encrypted credit card data is shown below:


{
  "amount" :  "1000",
  "card": {
    "owner": "sJEdXGTBSdVGrZq7dBrc0Q==",
    "brand": "VISA",
    "number": "44D22AuX5Kpkh3ikBiQKjPLNdu/KRw7/C1OYY9L549A=",
    "expiration": "NHGI+g5uD8tsA+uvqGsqYQ==",
    "cvv": "7SV2eco0RRyiPVgUhVn0Xg=="
  },
  "concept": "cash-in from my credit card"
}

Where:


Request body parameters


Parameter Required Datatype Description
amount yes numeric Amount of money to cash in
card yes object A card object
concept no string Optional description with the purpose of the card cash-in

Card object


Parameter Required Datatype Description
brand yes string Brand of the credit/debit card (unencrypted). Should be VISA or MCAR for Mastercard cards
cvv yes string Encrypted CVV of the credit/debit card
expiration yes string Encrypted expiration date of the credit/debit card in MMYY format
number yes string Encrypted number of the credit/debit card
owner yes string Encrypted full name of the owner of the credit/debit card

If card data is encrypted with an old temporal private key, it is not encrypted properly or data is not correct, API request will response with a Bad Request with the following body: 


{
  "errors": [
    {
      "status": 400,
      "detail": "Card data not encrypted."
    }
  ]
}

As a summary, steps needed to make a cash-in operation are the following:

  • Get temporal private key from the API.
  • Decrypt AES temporal private with your RSA private key.
  • Use decrypted temporal AES key to encrypt credit/debit card data using AES 256 ECB
  • Call cash-in API with encrypted card data and amount


Movement generated


This action will generate a movement of type CARD_CASHIN that will turn its status from PENDING to SUCCESS when the operation has been finished.


If you want to try this functionality yourself and learn more about the card cash-in, please go to the API catalogue.



SEPA Cash-in


Another option to fund the user's ioCash wallet is through a SEPA cash-in. With this method, a bank transfer is done from an external bank account to the IBAN associated to the user's ioCash wallet. This implies that you do not need to make any request against the API for the accomplishment of this action. The system will read the change in the IBAN and update the ioCash wallet balance. Since the operation is a bank transfer, it can take some time from the order of the cash-in till it reaches ioCash.


Movement generated


This action will generate a movement of type BANK_ACCOUNT_CASHIN that will turn its status from PENDING to SUCCESS when both the available balance (DLT account balance) and the total balance (system balance) are increased with the quantity cashed in.



Cash-out


In order for a user to send money from his IoCash wallet to another bank account, the following request has to be sent.


HTTP Request


POST /api/v1/public/wallets/{walletId}/cashOuts where the walletId is the UUID of the wallet, which should execute the money cash-out. In our example, the whole request will be /api/v1/public/wallets/cd496094-a77a-4e4e-bcd9-3361ff89294a/cashOuts.


With the following information provided as JSON:


{
  "iban": {
    "accountNumber": "ES7921000813610123456789"
  },
  "amount": "1.50",
  "concept": "Cash out from my account"
}

Where:


Request body parameters


Parameter Required Datatype Description
iban yes object An IBAN object
amount yes string The cash.out amount represented as integer or numeric value
concept no string Optional description with the purpose of the card cash-out

IBAN object


Parameter Required Datatype Description
accountNumber yes string The IBAN of the bank account, which should receive the payment


Movement generated


This action will generate a movement of type BANK_ACCOUNT_CASHOUT that will turn its status from PENDING to SUCCESS when both the available balance (DLT account balance) and the total balance (system balance) are decreased with the quantity cashed out.


If you want to try this functionality yourself and learn more about the cash-out, please go to the API catalogue.




Cash-out to favourite external account


In order for a user to send money from his IoCash wallet to a one of his favourite external accounts, the following request has to be sent.


HTTP Request


POST /api/v1/public/wallets/{walletId}/cashout-to-favourite-external-account where the walletId is the UUID of the wallet, which should execute the money cash-out. In our example, the whole request will be /api/v1/public/wallets/cd496094-a77a-4e4e-bcd9-3361ff89294a/cashout-to-favourite-external-account.


With the following information provided as JSON:


{
  "favouriteExternalAccountId": "91af1cb8-1caa-47d0-8ef8-2c11948baaba",
  "amount": "1.50",
  "concept": "Cash out from my account to my favourite external account"
}

Where:


Request body parameters


Parameter Required Datatype Description
favouriteExternalAccountId yes UUID Id of the favourite external account that you want to send the money
amount yes string The cash out amount represented as integer or numeric value
concept no string Optional description with the purpose of the cash-out

As response, you will get the following JSON object:


{
  "_links": {
    "self": {
      "href": "/api/v1/public/wallets/c86db278-6eb4-4af2-b023-753eba091d1c/movements/4fa85f64-5717-4562-b3fc-2c963f66afa7"
    }
  },
  "movementId": "4fa85f64-5717-4562-b3fc-2c963f66afa7",
  "status": "PENDING",
  "amount": "1.50",
  "favouriteExternalAccountIban": "ES0221004440760100171757",
  "favouriteExternalAccountId": "91af1cb8-1caa-47d0-8ef8-2c11948baaba",
  "alias": "My favourite account"
}

Where:

HTTP Response parameters


Parameter Datatype Description
movementId UUID The id of the movement generated
status string The movement status
amount BigDecimal The amount transfered to the external account
favouriteExternalAccountIban string External account number
favouriteExternalAccountId UUID The id of the favourite external account
alias string Alias that represent the favourite external account.


Movement generated


This action will generate a movement of type BANK_ACCOUNT_CASHOUT that will turn its status from PENDING to SUCCESS when both the available balance (DLT account balance) and the total balance (system balance) are decreased with the quantity cashed out.


If you want to try this functionality yourself and learn more about the cash-out, please go to the API catalogue.




Transfer


In ioCash, transfers can be originated by calling the API or by directly calling to the smart contract.



Transfer via API


To make a transfer via API you have to make the following request:


HTTP Request


POST /api/v1/public/wallets/{walletId}/transfer where the walletId is the UUID of the wallet, which should execute the money transfer. In our example, the whole request will be /api/v1/public/wallets/cd496094-a77a-4e4e-bcd9-3361ff89294a/transfer.


With the following information provided as JSON:


{
  "amount": "1.50",
  "concept": "Centralized transfer from API",
  "targetWalletId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Where:


Request body parameters


Parameter Required Datatype Description
amount yes string The amount to be transfered represented as integer or numeric value
concept no string Optional description with the purpose of the transfer
targetWalletId yes string UUID of the recipient wallet that will receive the transfer


Transfer via smart contract


You can directly use the methods on our smart contracts to make transfers without the need of going through the API. This will specially serve you when you want to trigger transfers after other conditions in other smart contracts are fulfilled. There are two different types of decentralized transfers:

  • One-step transfers: The transfer is directly executed after KYC limits are checked on-chain. After completion, the available balance of both accounts are updated. Then, the EME license agent will be notified about the transfer and the total balance of both users will be updated.
  • Two-step transfers: The transfer requires of an offchain third-party verification. There is one first transaction in which the user orders the transfer -here the KYC limits are checked and the available balance of the sender is updated- and a second one in which the designated operator accepts or rejects the transfer. After that, the available and total balances of sender and receiver are updated accordingly

Methods on DLT


To make a one-step transfer you have to call the transfer method that resides in our token contract.

To make a two-step transfer you have to call the orderTransfer method that resides in our token contract.

For more details check the Interacting with EmToken docs

You must make this call through the web3 api, and be connected to a network node in order to perform this operation in the DLT.



Movements generated


All three types of transfers explained above will generate two movements:


  1. Movement of type TRANSFER_OUT that will turn its status from PENDING to SUCCESS when both the sender user's wallet available balance (DLT account balance) and the total balance (system balance) are decreased with the transferred quantity.

  2. Movement of type TRANSFER_IN that will turn its status from PENDING to SUCCESS when both the receiver user's wallet available balance (DLT account balance) and the total balance (system balance) are increased with the transferred quantity.


Cross ledger transfer


If you have wallets in different networks you can tranfser money among them using cross ledger transfers. This functionality is only available via smart contract.


Via smart contract


To access this functionality you have to use the CrossLedgerLink smart contracts methods.


Methods on DLT


To order a cross ledger transfer the user has to call the orderTransfer method that resides in our CrossLedgerLink contract. In addition, you can retrieve the information of a cross ledger transfer by using the method getTransferData. Since the transfer is ordered, there are several checks done centrally by the platform and the transfer status is updated to different statuses. Though this life cycle, money is transitioned to/from suspense accounts and minted/burned in the destination and origin networks.

For more information about the methods and the functioning of cross ledger transfers, check the smart contract docs.


Movements generated


  1. Movement of type TRANSFER_OUT that will turn its status from PENDING to SUCCESS after the transfer has been confirmed and executed in both networks and the sender's wallet available balance and the total balance are decreased with the transferred quantity.

  2. Movement of type TRANSFER_IN that will turn its status from PENDING to SUCCESS after the transfer has been confirmed and executed in both networks and the receiver's wallet available balance and the total balance are increased with the transferred quantity.


Holds


In ioCash, holds can be originated by calling the API or by directly calling to the smart contract.


Holds make funds unavailable to users until they are executed.

When a hold is declared, the user has to define the amount that will be blocked in his/her account, the target account that will receive the money when the hold is executed and the notary that will decide if the hold execution is accepted (the money is sent to the target account) or rejected (the money is unlocked in the sender's account).

Create hold


Via API


To create a hold via API you have to make the request shown below. For holds via API, the bank is always set as the notary in the dlt. Therefore, a hold created via API has to be executed or released via API as well.


HTTP Request


POST /api/v1/public/wallets/{walletId}/hold where the walletId is the UUID of the wallet, which should hold the money. In our example, the whole request would be /api/v1/public/wallets/cd496094-a77a-4e4e-bcd9-3361ff89294a/hold.


With the following information provided as JSON:


{
  "amount": "1.50",
  "targetWalletId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "concept": "Centralized hold from API",
  "expiration": "2020-02-06T10:04:45+02"
}

If you leave the field "expiration" empty, the hold will be created perpetual i.e. it will never expired.


Where:


Request body parameters


Parameter Required Datatype Description
amount yes string The amount to be held represented as integer or numeric value
targetWalletId yes string UUID of the recipient wallet that will receive the transfer after the execution of the hold
concept no string Optional description with the purpose of the hold
expiration no Date Date in UTC time format in which the hold is expired. When expired, the held amount is automatically made available on the origin account. You can add/substract the time zone you want from UTC. In our example we are adding +02. If you leave the field "expiration" empty, the hold will be created perpetual i.e. it will never expire.


Via smart contract


You can directly use the methods on our smart contracts to create holds without the need of going through the API. This will specially serve you when you want to trigger holds after other conditions in other smart contracts are fulfilled. For these cases, any dlt address can be set as the notary, including another smart contract address. A decentralized hold cannot be executed or released via API (unless the bank address was set as notary).


Methods on DLT


To create a hold the user has to call the hold method that resides in our token contract. The hold can also be done on behalf of another user using holdFrom if he/she has beforehand given permission to the orderer using authorizeHoldOperator

For more information about all the hold methods you can check the Interacting with EmToken docs.


Movements generated


Hold creations generate LOCK movements.

Execute hold


Via API


To execute a hold via API you have to make the following request:


HTTP Request


POST /api/v1/public/wallets/{walletId}/hold/{holdId}/executeHold where the walletId is the UUID of the wallet that created the hold, which should transfer the money, and the holdId is the UUID of the hold which should be executed. In our example, the whole request will be /api/v1/public/wallets/cd496094-a77a-4e4e-bcd9-3361ff89294a/hold/3fa85f64-5717-4562-b3fc-2c963f66afa6/executeHold.


With the following information provided as JSON:


{
  "amount": "1.50",
  "concept": "Execute hold from API"
}

Where:


Request body parameters


Parameter Required Datatype Description
amount yes string The amount to be executed represented as integer or numeric value
concept no string Optional description with the concept of the execution


When a hold is executed, it is automatically closed. If the amount of the execution is less than the amount on hold, the difference will be released to the origin account. In order to be able to execute a partial hold and keep it open, there is a specific method. To do this you must make the following request



HTTP Request


POST /api/v1/public/wallets/{walletId}/hold/{holdId}/executeHoldAndKeepOpen where the walletId is the UUID of the wallet that created the hold, which should transfer the money, and the holdId is the UUID of the hold which should be executed. In our example, the whole request would be /api/v1/public/wallets/cd496094-a77a-4e4e-bcd9-3361ff89294a/hold/3fa85f64-5717-4562-b3fc-2c963f66afa6/executeHoldAndKeepOpen.


With the following information provided as JSON:


{
  "amount": "1.50",
  "concept": "Execute hold and keep open from API"
}

Where:


Request body parameters


Parameter Required Datatype Description
amount yes string The amount to be executed represented as integer or numeric value
concept no string Optional description with the concept of the execution

In partial executes, the hold is left open and will accept further operations as other executes or a release.



Via smart contract


You can directly use the methods on our smart contracts to execute holds or execute holds and keept open without the need of going through the API. This will specially serve you when you want to trigger holds after other conditions in other smart contracts are fulfilled.


Methods on DLT


To execute a hold the address that was defined as notary should call the executeHold method. The money will be transferred from the sender to the receiver.

To execute a hold and keep it open the address that was defined as notary should call the executeHoldAndKeepOpen method. The money will be transferred from the sender to the receiver.

For more information about all the hold methods you can check the Interacting with EmToken docs.


Movements generated


Hold executions generate transfers that create movements TRANSFER_OUT and TRANSFER_IN as explained above for the transfer operation.


Release hold


Via API


To release a hold via API you have to make the following request:


HTTP Request


POST /api/v1/public/wallets/{walletId}/hold/{holdId}/releaseHold where the walletId is the UUID of the wallet, which created the hold. In our example, the whole request would be /api/v1/public/wallets/cd496094-a77a-4e4e-bcd9-3361ff89294a/hold/3fa85f64-5717-4562-b3fc-2c963f66afa6/releaseHold.


With the following information provided as JSON:


{
  "concept": "Centralized release hold from API"
}

Where:


Request body parameters


Parameter Required Datatype Description
concept no string Optional description with the purpose of the release hold


Via smart contract


You can directly use the methods on our smart contracts to release holds without the need of going through the API.


Methods on DLT


To release a hold the notary has to call the releaseHold method. The money will be not sent to the receiver but unlocked into the sender's wallet so that he/she can use it again.

For more information about all the hold methods you can check the Interacting with EmToken docs.


Movements generated


Hold releases generate RELEASE movements.

Renew hold


Via API


Renews are used to change the expiration time of an existing hold. You can also change a hold from/to perpetual (it does not expire) by leaving the field expiration empty.To renew a hold via API you have to make the following request:


HTTP Request


POST /api/v1/public/wallets/{walletId}/hold/{holdId}/renewHold where the walletId is the UUID of the wallet, which created the hold. In our example, the whole request will be /api/v1/public/wallets/cd496094-a77a-4e4e-bcd9-3361ff89294a/hold/3fa85f64-5717-4562-b3fc-2c963f66afa6/renewHold.


With the following information provided as JSON:


{
  "expiration": "2020-02-07T09:25:18+02"
}

Where:


Request body parameters


Parameter Required Datatype Description
expiration no Date Date in UTC time format in which the hold is expired. You can add/substract the time zone you want from UTC. In our example we are adding +02. If you leave the field "expiration" empty, the hold will be renewed perpetual i.e. it will never expire.


Via smart contract


You can directly use the methods on our smart contracts to create holds without the need of going through the API. This will specially serve you when you want to trigger holds after other conditions in other smart contracts are fulfilled.


Methods on DLT


To renew a hold the issuer or payer has to call the renewHold method. The expiration time will be updated.

For more information about all the hold methods you can check the Interacting with EmToken docs.

Get Hold info


You can check the information of holds from our API by using the following request


HTTP Request


GET /api/v1/public/wallets/{walletId}/holds/{holdId} where the parameter walletId in our example would be: cd496094-a77a-4e4e-bcd9-3361ff89294a and the holdID can be for example b2462ed0-d3d7-4c8a-abc3-980fd4472876. Therefore, the whole request would look like this: /api/v1/public/wallets/cd496094-a77a-4e4e-bcd9-3361ff89294a/holds/b2462ed0-d3d7-4c8a-abc3-980fd4472876.


HTTP Response


As response, you will get a JSON with all the information of the requested hold. 


{
  "_links": {
    "self": {
      "href": "/api/v1/public/wallets/cd496094-a77a-4e4e-bcd9-3361ff89294a/holds/b2462ed0-d3d7-4c8a-abc3-980fd4472876"
    },
    "payerWallet": {
      "href": "/api/v1/public/users/cd496094-a77a-4e4e-bcd9-3361ff89294a"
    },
    "payeeWallet": {
      "href": "/api/v1/public/wallets/66a79523-6234-4590-857b-3e745fc41c28"
    }
  },
  "id": "b2462ed0-d3d7-4c8a-abc3-980fd4472876",
  "userId": "421fd6a5-95e8-4e90-9ce5-c14fa0904754",
  "clientId": "619b4a82-0e68-4f16-bb00-a4a6a250df69",
  "issuerDltAddress": "0x95066cdf6a5ac9489eeb28755f0e878eb3de711d",
  "payerDltAddress": "0x95066cdf6a5ac9489eeb28755f0e878eb3de711d",
  "payeeDltAddress": "0x0e1ff5c25bF0132D476ff999096c21A41143FB4A",
  "notaryDltAddress": "0x7c311A5E1b9fED7E56eC37d493901bBcb9063D02",
  "heldValue": 10.00,
  "executedValue": 8.00,
  "status": "EXECUTED",
  "dltNetwork": "AlastriaTelsius",
  "contractAddress": "0xAC69155Cf549078bDE41890685f4bEB1f496a527",
  "operationId": "q13",
  “payerWalletId": "cd496094-a77a-4e4e-bcd9-3361ff89294a",
  “payeeWalletId": "66a79523-6234-4590-857b-3e745fc41c28",
  "createdAt": "2019-12-17T17:38:31.112+0000",
  "expiration": "2019-12-18T17:38:31.112+0000"
}


Where:


HTTP Response parameters


Parameter Datatype Description
id string UUID of the hold
userId string UUID of the user where the hold is created
clientId string UUID of the client
issuerDltAddress string DLT address associated to the users's wallet that has created the hold
payerDltAddress string DLT address associated to the users's wallet where the hold has been created
payeeDltAddress string DLT address associated to the users's wallet receiver
notaryDltAddress string DLT address that has been set as the notary of the hold. The notary can execute or cancel the hold
heldValue numeric Amount of money that was put on hold with the creation of the hold
executedValue numeric Amount of money that has been sent to the payee out of the hold so far
status string The status can be either CREATION_REQUESTED, PENDING_DLT_CREATION, CREATED, CREATION_FAILED, PENDING_DLT_EXPIRATION, EXECUTION_REQUESTED, PENDING_DLT_EXECUTION, EXECUTED, EXECUTION_FAILED, EXECUTION_AND_KEEP_OPEN_REQUESTED, PENDING_DLT_EXECUTE_AND_KEPT_OPEN, EXECUTED_AND_KEPT_OPEN, EXECUTION_AND_KEPT_OPEN_FAILED, RELEASE_REQUESTED, PENDING_DLT_RELEASE, RELEASE_FAILED, RELEASED_BY_NOTARY, RELEASED_BY_PAYEE, RELEASED_ON_EXPIRATION, RENEWAL_REQUESTED, PENDING_DLT_RENEWAL, RENEWED or RENEWAL_FAILED
dltNetwork string Blockchain network in which the hold is done
contractAddress string Ethereum address of the smart contract where the hold has been created
operationId string Identifier of the hold in the smart contract. It has to be unique inside its smart contract
payerWalletId string UUID of the wallet where the hold has been created
payeeWalletId string Payer wallet id
createdAt string Timestamp of the movement creation
expiration Date Date in UTC time format in which the hold is expired. When expired, the held amount is automatically made available on the origin account. You can add/substract the time zone you want from UTC.



Get holds list


If you want to get the list of all the holds of a specific wallet make the following request:


HTTP Request


GET /api/v1/public/wallets/{walletId}/holds

As a response, you will get a JSON array with the information of all the holds of that wallet.

The call can be paged. This is specially usefull when you have to retrieve a big amount of elements.

By default, the size of the page is 20 elements, and you can put a maximum size of 2000 elements. The response shows a list of resources to make the paged calls, basically you can set the page, the size, and the field you want to sort the list by.

Example:

If you want to try any of these functionalities yourself and know more about them, please go to the API catalogue.

Scheduled operations


With this functionality you can schedule payments to be executed in the future as well as set recurrent payments for your wallets.


The target of these operations can be either another wallet of your application, a favourite external bank account or a nex external bank account.

The recurrence of payments can be set with end date, with a number of repetitions or endless.

Create Scheduled Operation


To create an scheduled operation you have to make the request shown below. All possible body parameters for all cases are explained below.


HTTP Request


POST /api/v1/public/wallets/{walletId}/scheduled-operations where the walletId is the UUID of the wallet, which will transfer the money. In our example, the whole request would be /api/v1/public/wallets/cd496094-a77a-4e4e-bcd9-3361ff89294a/scheduled-operations.


With the following information provided as JSON:


{
  "alias": "operation 1",
  "concept": "recurrent payment 1",
  "amount": 100.5,
  "receiver": {
    "type": "FAVOURITE_EXTERNAL_BANK_ACCOUNT",
    "account": "79d8a4be-c934-4ffe-ad10-3982f1a30006"
  },
  "schedule": {
    "startDate": "2020-04-23T00:00:00.000+02",
    "frequency": "DAILY",
    "duration": {
      "type": "NUMBER_OF_REPETITIONS",
      "value": "2"
     }
  }
}

Where:


Request body parameters


Parameter Required Datatype Description
alias yes string Alias of the operation. The alias is unique per wallet.
concept no string Optional concept that will be included in movements related to the operation. If not provided, a default one will be set by the system.
amount yes numeric Amount of the operation.
receiver yes object Receiver information.
schedule yes object Schedule information.

Receiver object


Parameter Required Datatype Description
type yes string Can be IOCASH_WALLET for a target wallet id, FAVOURITE_EXTERNAL_BANK_ACCOUNT for a favourite external bank account id or EXTERNAL_BANK_ACCOUNT for a not saved external bank account.
account yes string It is a wallet UUID string if the receiver type is IOCASH_WALLET, a favourite external bank account UUID string if the receiver type is FAVOURITE_EXTERNAL_BANK_ACCOUNT and an IBAN number string is receiver type is EXTERNAL_BANK_ACCOUNT.

Schedule object


Parameter Required Datatype Description
startDate yes string Date and time in UTC format the scheduled operation should start. If frequency is ONCE, it is the date in which the unique operation will be executed.
frequency yes string Can be ONCE for unique execution in the future, DAILY for daily executions, WEEKLY for weekly executions, MONTHLY for monthly executions and YEARLY for yearly executions. The time of the day of the future executions is the same as the time of the start date, for example, if you schedule a DAILY operation with start date at 13:00, next day the operation will be executed at the same time. In addition, for a monthly operation, if it is scheduled with a start date on the 31st of a month, it will execute on the last day of each month.
duration no object Duration object. Does not apply when frequency is ONCE.

Duration object


Parameter Required Datatype Description
type yes string Duration type. Can be ENDLESS if the operation does not have end date, NUMBER_OF_REPETITIONS if you want your operation to be executed a certain number of times, or END_DATE if you want to provide an end date for the operation.
value no string Depends on the type. Does not apply when duration type is ENDLESS. For NUMBER_OF_REPETITIONS duration type should be a valid positive integer number. For END_DATE should be a valid date in UTC format greater than start date. The end date should be expressed in the format yyyy-MM-dd without time, if expressed with time, the time will not be taken into account.

Movements generated


All types of receiver explained above can generate three type of movements:


  1. Movement of type TRANSFER_OUT when receiver type is IOCASH_WALLET for the source wallet.

  2. Movement of type TRANSFER_IN when receiver type is IOCASH_WALLET for the target wallet.

  3. Movement of type CASH_OUT when receiver type is FAVOURITE_EXTERNAL_BANK_ACCOUNT or EXTERNAL_BANK_ACCOUNT for the source wallet.

Get Scheduled Operation info


You can check the information of scheduled operations from our API by using the following request


HTTP Request


GET /api/v1/public/wallets/{walletId}/scheduled-operations/{scheduledOperationId} where the parameter walletId in our example would be: cd496094-a77a-4e4e-bcd9-3361ff89294a and the scheduledOperationId can be for example 7f923d0b-0455-4b22-a489-67513eff2b7d. Therefore, the whole request would look like this: /api/v1/public/wallets/cd496094-a77a-4e4e-bcd9-3361ff89294a/scheduled-operations/7f923d0b-0455-4b22-a489-67513eff2b7d.


HTTP Response


As response, you will get a JSON with all the information of the requested scheduled operation. 


{
  "id": "7f923d0b-0455-4b22-a489-67513eff2b7d",
  "alias": "operation 26",
  "concept": "testing",
  "amount": 0.10,
  "status": "ACTIVE",
  "schedule": {
    "startDate": "2020-05-04T06:48:00.000+0000",
    "nextDate": "2020-05-05T06:48:00.000+0000",
    "frequency": "DAILY",
    "duration": {
      "type": "END_DATE",
      "endDate": "2020-05-07",
      "numberOfRepetitions": 4
    }
  },
  "receiver": {
    "type": "IOCASH_WALLET",
    "account": "877bd6b7-ed92-49e2-8e59-cc814fdb1000"
  },
  "createdAt": "2020-05-04T06:47:19.569+0000",
  "_links": {
    "self": {
      "href": "/api/v1/public/wallets/a611e619-16ec-4e81-b24b-bbc52cbb61ba/scheduled-operations/7f923d0b-0455-4b22-a489-67513eff2b7d"
    }
  }
}


Where:


HTTP Response parameters


Parameter Datatype Description
id string UUID of the scheduled operation.
alias string Unique alias of the scheduled operation.
concept string Concept of the scheduled operation.
amount numeric Amount of the scheduled operation.
status string Status of the scheduled operation. Can be ACTIVE, DELETED or COMPLETED.
schedule object Schedule information of the scheduled operation.
receiver object Receiver information of the scheduled operation.
createdAt date Creation date of the scheduled operation.

Receiver object


Parameter Datatype Description
type string Can be IOCASH_WALLET, or FAVOURITE_EXTERNAL_BANK_ACCOUNT, or EXTERNAL_BANK_ACCOUNT for an IBAN number.
account string It is a wallet id UUID string if the receiver type is IOCASH_WALLET, a favourite external bank account id UUID string if the receiver type is FAVOURITE_EXTERNAL_BANK_ACCOUNT and an IBAN number string is receiver type is EXTERNAL_BANK_ACCOUNT.

Schedule object


Parameter Datatype Description
startDate string Date and time in UTC format the scheduled operation should start. If frequency is ONCE, it is the date in which the unique operation will be executed.
frequency string Can be ONCE for unique execution in future, DAILY for daily executions, WEEKLY for weekly executions, MONTHLY for monthly executions and YEARLY for yearly executions.
duration object Duration object. Not filled when frequency is ONCE.

Duration object


Parameter Datatype Description
type string Duration type. Can be ENDLESS, or NUMBER_OF_REPETITIONS, or END_DATE.
value string Depends on the type. Not filled if type is ENDLESS. For NUMBER_OF_REPETITIONS duration type is be a valid positive integer number. For END_DATE is be a valid date in UTC format. The end date is returned expressed in the format yyyy-MM-dd without time.

Get Scheduled Operations list


If you want to get the list of all the scheduled operations of a specific wallet make the following request:


HTTP Request


GET /api/v1/public/wallets/{walletId}/scheduled-operations

As a response, you will get a JSON array with the information of all the scheduled operations of that wallet.

The call can be paged. This is specially useful when you have to retrieve a big amount of elements.

By default, the size of the page is 20 elements, and you can put a maximum size of 2000 elements. The response shows a list of resources to make the paged calls, basically you can set the page, the size, and the field you want to sort the list by.

Example:

If you want to try any of these functionalities yourself and know more about them, please go to the API catalogue.

Get Scheduled Operation executions list


You can check all executions of an scheduled operation. This endpoint retrieves the executions that have been done and also future executions, with a maximum number of 10.


HTTP Request


GET /api/v1/public/wallets/{walletId}/scheduled-operations/{scheduledOperationId}/executions where the parameter walletId in our example would be: cd496094-a77a-4e4e-bcd9-3361ff89294a and the scheduledOperationId can be for example b2462ed0-d3d7-4c8a-abc3-980fd4472876. Therefore, the whole request would look like this: /api/v1/public/wallets/cd496094-a77a-4e4e-bcd9-3361ff89294a/scheduled-operations/b2462ed0-d3d7-4c8a-abc3-980fd4472876/executions.


HTTP Response


As response, you will get a JSON with all the information of the scheduled operation executions.

The call can be paged. Only executions can be paged, as scheduled executions only retrieve 10 future executions by default. This is specially useful when you have to retrieve a big amount of elements.

By default, the size of the page is 20 elements, and you can put a maximum size of 2000 elements. The response shows a list of resources to make the paged calls, basically you can set the page, the size, and the field you want to sort the list by.


{
  "_links": {
    "self": {
      "href": "/api/v1/public/wallets/cd496094-a77a-4e4e-bcd9-3361ff89294a/scheduled-operations/b2462ed0-d3d7-4c8a-abc3-980fd4472876/executions?page=0&size=20&sort=createdAt,desc"
    },
    "first": {
      "href": "/api/v1/public/wallets/cd496094-a77a-4e4e-bcd9-3361ff89294a/scheduled-operations/b2462ed0-d3d7-4c8a-abc3-980fd4472876/executions?page=0&size=20&sort=createdAt,desc"
    },
    "last": {
      "href": "/api/v1/public/wallets/cd496094-a77a-4e4e-bcd9-3361ff89294a/scheduled-operations/b2462ed0-d3d7-4c8a-abc3-980fd4472876/executions?page=0&size=20&sort=createdAt,desc"
    }
  },
  "_embedded": {
    "executions": {
      "id": "c81e9548-8e3c-4a14-9ee8-fd546d6c55b0",
      "status": "EXECUTED",
      "date": "2020-05-04T06:48:00.394+0000",
      "_links": {
        "movement": {
          "href": "/api/v1/public/wallets/cd496094-a77a-4e4e-bcd9-3361ff89294a/movements/c81e9548-8e3c-4a14-9ee8-fd546d6c55b0"
        }
      }
    },
    "scheduledExecutions": [
      {
        "status": "SCHEDULED",
        "date": "2020-05-05T06:48:00.000+0000"
      },
      {
        "status": "SCHEDULED",
        "date": "2020-05-06T06:48:00.000+0000"
      },
      {
        "status": "SCHEDULED",
        "date": "2020-05-07T06:48:00.000+0000"
      }
    ]
  },
  "page": {
    "size": 20,
    "totalElements": 1,
    "totalPages": 1,
    "number": 0
  }
}


Where:


HTTP Response parameters


Parameter Datatype Description
executions list List of executions that has been triggered. Can be in status TRIGGERED, EXECUTED or FAILED.
scheduledExecutions list List of future executions in status SCHEDULED. Only 10 are returned as maximum.

Execution object


Parameter Datatype Description
id string UUID id for the execution. Not filled for scheduled executions.
status string Can be TRIGGERED, or EXECUTED, or FAILED, or SCHEDULED for future executions.

Delete Scheduled Operation


When you delete a scheduled operation, all the associated future programmed executions will be cancelled.


HTTP Request


DELETE /api/v1/public/wallets/{walletId}/scheduled-operations/{scheduledOperationId} where the parameter walletId in our example would be: cd496094-a77a-4e4e-bcd9-3361ff89294a and the scheduledOperationId can be for example b2462ed0-d3d7-4c8a-abc3-980fd4472876. Therefore, the whole request would look like this: /api/v1/public/wallets/cd496094-a77a-4e4e-bcd9-3361ff89294a/scheduled-operations/b2462ed0-d3d7-4c8a-abc3-980fd4472876.


HTTP Response


As response, you will get a JSON with the information of the deleted scheduled operation. The parameters are the same as in the Get Scheduled Operation info request.


{
  "id": "7f923d0b-0455-4b22-a489-67513eff2b7d",
  "alias": "operation 26",
  "concept": "testing",
  "amount": 0.10,
  "status": "DELETED",
  "schedule": {
    "startDate": "2020-05-04T06:48:00.000+0000",
    "nextDate": "2020-05-05T06:48:00.000+0000",
    "frequency": "DAILY",
    "duration": {
      "type": "END_DATE",
      "endDate": "2020-05-07",
      "numberOfRepetitions": 4
    }
  },
  "receiver": {
    "type": "IOCASH_WALLET",
    "account": "877bd6b7-ed92-49e2-8e59-cc814fdb1000"
  },
  "createdAt": "2020-05-04T06:47:19.569+0000",
  "_links": {
    "self": {
      "href": "/api/v1/public/wallets/a611e619-16ec-4e81-b24b-bbc52cbb61ba/scheduled-operations/7f923d0b-0455-4b22-a489-67513eff2b7d"
    }
  }
}

If the wallet is not in status READY or the scheduled operation is not in status ACTIVE, an error will be returned.