When a user wants to withdraw to a specific account, you ask him for the account id he wants to withdraw to.
When you receive this account id, you must first check if that account has a public key attached to it or not (i.e. if it’s new or not).

To do this, you must use the getAccountPublicKey API. It takes 1 parameter, account.

account – account you want the public key of

http://localhost:6876/burst?requestType=getAccountPublicKey&account=BURST-C6L6-UQ5W-RBJK-AWDSJ

If the account does not have a public key, you will get this error: { "errorCode": 5, "errorDescription": "Unknown account" }
When you get this error, you should also ask the user for his public key or at least display a warning explaining the risk of using an account without a public key.

When you have both the account id and public key, you can verify that they are correct by comparing the given account id with the account id generated by the public key using the getAccountID API call.

  1. secretPhrase – account passphrase
  2. publicKey – account public key

We want to calculate only by publicKey so our request looks like this:

http://localhost:6876/burst?requestType=getAccountId&publicKey=28f56a81e0f8555b07eacffd0e697b21cbbbdf3cf620db14522732b763564f13

You’ll get back a response like this: {"accountRS":"BURST-C6L6-UQ5W-RBJK-AWDSJ","publicKey":"28f56a81e0f8555b07eacffd0e697b21cbbbdf3cf620db14522732b763564f13","requestProcessingTime":0,"account":"9827273118446850628"}

Now compare the response accountRS to the account id the user provided.
If they are equal, you can go ahead and perform the withdrawal.

Sending BURST

Sending BURST is done via the sendMoney API call. The relevant parameters are:

  1. recipient – recipient’s account address
  2. amountNQT – amount of BURST (in NQT)
  3. feeNQT – transaction fee for the transaction in NQT.
  4. secretPhrase – sender’s account passphrase
  5. deadline – deadline for the transaction in minutes. Should be set to the maximum value of 1440
  6. recipientPublicKey – recipient public key as provided by the user, only needed if the user account has no public key yet (on first transaction)

At the moment (v1.9.2) the recipientPublicKey is optional, however not specifying it, puts the user’s funds at risk. The recipientPublicKey is mandatory in case you like to attach an encrypted message to the withdrawal transaction of a new account.

This request has to be sent using HTTP POST.

The response should look like this if everything went OK: { "fullHash": “10788f7ad3f145b5209da6145327d7fed869…”, ... a lot more information ... }
A correctly executed response should always contain the “transaction” field which represents the newly created transaction id.
If there’s an error, you may get a response such as this (other errors may apply):{ "errorCode": 5, "errorDescription": "Unknown account" }

Adding a Message To a (Payment) Transaction

You can add messages to any kind of transaction.

To do so, specify the below parameters in your request:

  1. message – plain text message.
  2. messageIsText – should be set to the string “true” if text.
  3. messageToEncrypt – plain text message that should be encrypted.
  4. messageToEncryptIsText – should be set to the string “true” if text.

In case you want to attach a plain text message, specify message and set messageIsText to “true”.

encrypt

If you want to attach an encrypted message that can only be read by the recipient, specify messageToEncrypt and set messageToEncryptIsText to “true”.
To create the messge you may use the encryptTo API call.

Note that these messages are not mutually exclusive, you can add both a plain text and encrypted message in the same transaction.
Allowing the user to add a message on your withdrawal page is recommended, so that you can coordinate with other services who use a message-based deposit system.

Hot and Cold Wallets

You should not keep all of your user’s deposits in a single hot wallet.
A hot wallet is a wallet for which the passphrase is stored somewhere on your server, so that you can send money from it.

Instead, you should have both a hot and cold wallet. The cold wallet should hold most of the coins and not be accessible from any of your servers. Ideally, you’d manually send from your cold wallet to your hot wallet when more coins are needed for day-to-day operations.

So the best thing to do is to have money sent to your cold wallet address, and then send out to your hot wallet manually when needed.