# Identifier & ReferenceId *Note: The code on this page should be regarded as pseudocode. Refer to the pages in the documentation describing the specific functions for details and fully correct examples.* ## Important Points * Deposit Addresses are permanently mapped to the identifier they were created with * Transactions *to* such an address will always include the identifier * `referenceId` is optional in deposit request. It allows you to identify individual transactions if you require more detailed control over deposits. * **NOTE:** `referenceId` expire after 24 hours. Deposits can still be made to the relevant addresses, but the `referenceId` will not be present in the callback * You can adjust this expiry timeframe in the [Callback Settings](https://docs.akashicpay.com/dashboard/developers#deposit-request-expiry-time). * If you add multiple `referenceIds` , using the same `identifier` and [Network](https://docs.akashicpay.com/introduction/terminology#network), they will get returned in order, oldest first, as long as they have not expired. (Unless using different [requested amounts](https://docs.akashicpay.com/guides/requested-amount-and-currency)) * `referenceId` is mandatory in payout. It allows you to identify individual payout transactions. **It is strongly recommended to keep a one-to-one mapping between users and deposit addresses.** #### Why? * A permanently assigned deposit-address means new wallets do not have to be created every time a deposit is initiated (or otherwise selected from a pre-generated pool through some algorithm). After requesting a deposit-address for an identifier, you know the identifier and address are linked forever and therefore would not need to request a deposit-address again for that identifier. Should you still want to check the address it is still much more efficient as AP will simply look up the wallet in a database instead of creating a new wallet on the blockchain - which can be a lengthy procedure. * If you manage a set of users, it will be easier for you to keep track of which user has which address used for deposits (as it will be only one, and always the same one). Similarly, your users will only have to deal with one address (or really one *per network*) for depositing, minimizing any risk of deposits going into the wrong wallet. ## Detailed Description In the documentation and the code, you will come across the concept of an `identifier`. The identifier is just that, something that uniquely identifies deposit addresses. Normally, the identifier will be a userId or similar, though it is up to you exactly how you use it. If you manage deposit requests, you can further identify a specific transaction by passing a unique ID to `referenceId`. It should be different from the identifier and both will be returned in the callback. For managing withdrawal requests, you can pass your withdrawal ID to `referenceId` directly, which will be return as `referenceId` in the callback. ## Deposits ### Creating a deposit address The first place you will encounter the identifier is usually when [creating a wallet](https://docs.akashicpay.com/sdk/functions/getdepositaddress) (deposit address) for your software, perhaps for one of your users to deposit funds into. If you control a number of users, it is likely you store their data with some unique property like an ID or a username. This could then be used in the call to get a deposit address: {% code overflow="wrap" %} ```typescript AkashicPay.getDepositAddress('TRX', 'user1') // -> 'TTVkK6hGoAFhaLh1NTkUDHjcFFXKmWcSdb' ``` {% endcode %} The returned address (TTVkK6hGoAFhaLh1NTkUDHjcFFXKmWcSdb in the above example) is now *permanently assigned* to the identifier `'user1'`. Any subsequent call of the same function will return the same address: {% code overflow="wrap" %} ```typescript AkashicPay.getDepositAddress('TRX', 'user1') // -> 'TTVkK6hGoAFhaLh1NTkUDHjcFFXKmWcSdb' ``` {% endcode %} If you change the Network or the identifier, you will naturally get a different address: 
AkashicPay.getDepositAddress('TRX', 'user2') 
// -> 'TDkteGBASJSvoHSeAAwej3LAfFLj7zhhaE'

AkashicPay.getDepositAddress('ETH', 'user1') 
// -> '0x159cA92b12F67E5676d82C238f4906692618A555' (diffrent format on Ethereum)
If you need to track individual deposits you must pass a unique id to referenceId: 
AkashicPay.getDepositAddress('TRX', 'user2', 'order1') 
// -> 'TDkteGBASJSvoHSeAAwej3LAfFLj7zhhaE'

AkashicPay.getDepositAddress('ETH', 'user1', 'order2')
// -> '0x159cA92b12F67E5676d82C238f4906692618A555' (different format on Ethereum)
If doing multiple calls with the same user on the same network, as below, it will create multiple orders waiting to be fulfilled: ```javascript AkashicPay.getDepositAddress('TRX', 'user1', 'order1') // -> 'TDkteGBASJSvoHSeAAwej3LAfFLj7zhhaE' // Creates an order 'order1' which is completed upon the first deposit AkashicPay.getDepositAddress('TRX', 'user1', 'order2') // -> 'TDkteGBASJSvoHSeAAwej3LAfFLj7zhhaE' (same address) // Creates an order 'order2' which is completed upon the second deposit ``` > Note that the same address is returned both times. There are now two "orders" waiting to be fulfilled, which will be completed in the order they were created. That means, the first deposit to the wallet will trigger a callback containing `"referenceId": "order1"` whereas the *second* deposit to the address will trigger a callback with `"referenceId": "order2"` . This assumes none of the orders have expired, which happens 24hrs after creation by default. ### Deposit Callbacks If the user we have identified as `user1` now decides to make a deposit to wallet `TTVkK6hGoAFhaLh1NTkUDHjcFFXKmWcSdb` you will receive a [callback](https://docs.akashicpay.com/callbacks/deposit-callbacks) to the URL(s) you setup on AkashicPay.com. Present in the callback object will be a field titled `identifier` with the value `user1`. This allows you to easily identify deposits with the user they belong to. Of course, if you'd like, you could store the address (TTV...) in your database and use that instead. If you include referenceId in `getDepositAddress`, it will be attached to the associated callbacks. ## Payouts/Withdrawals ### Processing payouts (withdrawals) For [payouts/withdrawals](https://docs.akashicpay.com/sdk/functions/payout) you must include an `referenceId` in the function-call. The `referenceId` must be something to identify a payout transaction. ```typescript AkashicPay.payout('tx1', 'TAzsQ9Gx8eqFNFSKbeXrbi45CuVPHzA8wr', '10', 'TRX', 'USDT') AkashicPay.payout('tx2', 'TAzsQ9Gx8eqFNFSKbeXrbi45CuVPHzA8wr', '5', 'TRX', 'USDT') ``` This will initiate a transaction from AkashicPay to external wallet TAzsQ... for the value of 10 USDT on the Tron (TRX) Network. Due to the way AkashicPay works, the withdrawal may be sent *from* one of many wallets. There is thus *no guarantee* (in fact, it is unlikely) that the withdrawal is sent from the same address uses for deposits, and you should *never* rely on this to be true. ### Payout Callbacks When the withdrawal is triggered using the function as above, you will again receive a [callback](https://docs.akashicpay.com/callbacks/payout-callbacks) to the URL(s) you have setup on AkashicPay.com. When you receive the payout-callback the transaction has been confirmed and it is safe to credit the user. ## Special Cases ### Payout without referenceId? Depending on your usage, there may be cases where including the `referenceId` seems unnecessary. For example doing an internal transaction to a special wallet or when doing a payout of profits. In general, for these sort of payouts that do not concern any users, the `referenceId` is largely superfluous. However, we still require the `referenceId` to be present for all transactions to ensure everything can be tracked unambiguously. This is due to the fact that there is no safe way to separate two transactions otherwise, as it is technically possible for two otherwise equal transactions to take place at the same time. We therefore encourage you to also keep track of all transactions using sensible `referenceId`. For example: {% code overflow="wrap" %} ```typescript AkashicPay.payout('INTERNAL_TRANSFER', 'TAzsQ9Gx8eqFNFSKbeXrbi45CuVPHzA8wr', '10', 'TRX', 'USDT') AkashicPay.payout('PROFIT_PAYOUT', 'TDprmTxVAkC7a8RuFNFB3ukysRMeGELXsM', '1000', 'TRX', 'USDT') ``` {% endcode %} Of course, any string-argument is permitted, so if you are absolutely sure you do not want to keep track of the transaction through the referenceId, you could just supply any random string and immediately forget about it: **NB!** Do *not* use an empty string! ```typescript AkashicPay.payout('foo', 'TAzsQ9Gx8eqFNFSKbeXrbi45CuVPHzA8wr', '10', 'TRX', 'USDT') AkashicPay.payout('NaN', 'TAzsQ9Gx8eqFNFSKbeXrbi45CuVPHzA8wr', '10', 'TRX', 'USDT') ``` ### Multiple deposit addresses? Of course, there is nothing preventing you from providing "user1" in your system with multiple deposit addresses. Perhaps one address will be used for special promotions or other cases. In this case, you could simply do something like: ```typescript AkashicPay.getDepositAddress('TRX', 'user1-normal') // -> 'TDprmTxVAkC7a8RuFNFB3ukysRMeGELXsM' AkashicPay.getDepositAddress('TRX', 'user1-special') // -> 'TRMzP9A18iQNvaFn33zkhhnN5exmLWZ5Ad' ``` Perhaps you store this on your user as e.g. {% code overflow="wrap" %} ``` { userId: 'user1', wallets: [{address: 'TDprmTxVAkC7a8RuFNFB3ukysRMeGELXsM', identifier: 'user1-normal'}, {address: 'TRMzP9A18iQNvaFn33zkhhnN5exmLWZ5Ad', identifier: 'user1-special'}] } ``` {% endcode %} As usual, any deposits to the above two addresses would now return the respective identifier. This is an example showcasing how AkashicPay *can* be used. However, we recommend always keeping a one-to-one mapping between user and deposit address for maximal efficiency and minimal potential for confusion.