Skip to main content

Identifier & ReferenceId

Identifier keeps track of wallets and ReferenceId keeps track of deposits as well as withdrawals.

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
    • If you add multiple referenceIds , using the same identifier and Network, they will get returned in order, oldest first, as long as they have not expired. (Unless using different requested amounts)
  • referenceId is mandatory in payout. It allows you to identify individual payout transactions.
  • The identifier field must contain only alphanumeric characters (a–z, A–Z, 0–9) and the following symbols: underscore (_), at sign (@), period (.), and hyphen (-).

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 (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:

AkashicPay.getDepositAddress('TRX', 'user1') 
// -> 'TTVkK6hGoAFhaLh1NTkUDHjcFFXKmWcSdb'

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:

AkashicPay.getDepositAddress('TRX', 'user1') 
// -> 'TTVkK6hGoAFhaLh1NTkUDHjcFFXKmWcSdb'

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:

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 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 you must include an referenceId in the function-call. The referenceId must be something to identify a payout transaction.

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 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:

AkashicPay.payout('INTERNAL_TRANSFER', 'TAzsQ9Gx8eqFNFSKbeXrbi45CuVPHzA8wr', '10', 'TRX', 'USDT')

AkashicPay.payout('PROFIT_PAYOUT', 'TDprmTxVAkC7a8RuFNFB3ukysRMeGELXsM', '1000', 'TRX', 'USDT')

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!

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:

AkashicPay.getDepositAddress('TRX', 'user1-normal') 
// -> 'TDprmTxVAkC7a8RuFNFB3ukysRMeGELXsM'
AkashicPay.getDepositAddress('TRX', 'user1-special') 
// -> 'TRMzP9A18iQNvaFn33zkhhnN5exmLWZ5Ad'

Perhaps you store this on your user as e.g.

{
    userId: 'user1',
    wallets: [{address: 'TDprmTxVAkC7a8RuFNFB3ukysRMeGELXsM', 
            identifier: 'user1-normal'},
             {address: 'TRMzP9A18iQNvaFn33zkhhnN5exmLWZ5Ad',
              identifier: 'user1-special'}]
}

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.