Tokenization
So you chose to implement your service through our Tokenization model, great! In this page we will guide you to achieve the basic operations you will need to perform as you advance with the development:
- Create and activate a new Customer
- Create Accounts for the Customer
- Perform a Funding operation
- Execute a Payment
- Perform a Payout operation
Create new customer
The creation of a Customer includes several aspects. For instance, an initial limit regarding the amount of transactions that can be executed will be set through the Trustlevels. During the customer creation, Nexus will create a blockchain account with the supplied address. In case Stellar is used for the tokenization, Nexus will also take care of creating a Stellar transaction envelope, which contains one or multiple signatures. Subsequently, Nexus will take care of creating a Stellar trustline between the newly created customer and the issuer of the token.
Create
| Request | Endpoint |
|---|---|
| POST | baseURL/customer |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Request body (JSON)
| Key | Value |
|---|---|
code |
(string) unique identifier for this customer |
trustlevelCode |
one of values you previously defined in the initial setup. |
account |
object that holds the following information: - address: (string) public key of the customer - tokenSettings: (object) following additional token settings: -- allowedTokens: (array of strings) listing the accepted token codes (e.g. "CUSD", "TOK"...) |
Submit
The last step to confirm the creation of a new customer is to sign the envelope returned in the previous step. Signing is done locally using a SDK or tools provided by the designated blockchain. The private key of the corresponding address given during Customer creation is required to sign. The signed envelope must be submitted by making a request to the following API endpoint:
| Request | Endpoint |
|---|---|
| POST | baseURL/token/envelope/submit |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Request body (JSON)
| Key | Value |
|---|---|
cryptoCode |
(required) (string) CryptoCode for the Envelope |
envelope |
(required) (string) encoded string of the transaction envelope signed by the Customer |
hash |
(string) |
cryptoCode |
(boolean) Do not verify that the envelope is already created |
Add an account
During Customer creation, an account will be automatically added. There can be use cases in which a customer wants to hold different accounts (e.g. due to different tokens). Nexus allows you to facilitate this process by calling the following endpoint to create additional accounts.
| Request | Endpoint |
|---|---|
| POST | baseURL/customer/{customerCode}/accounts |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Route parameters
| Key | Value |
|---|---|
CustomerCode |
(required) (string) unique identifier for this customer |
Request body (JSON)
| Key | Value |
|---|---|
address |
public key of the customer |
tokenSettings |
an object holding the following additional token settings |
allowedTokens |
array listing the accepted token codes (e.g. "CUSD", "TOK"...) |
As in the customer's creation procedure, the call to the submit endpoint will also be called to finalize the operation and add it to the Stellar ledger.
| Request | Endpoint |
|---|---|
| POST | baseURL/token/envelope/submit |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Request body (JSON)
| Key | Value |
|---|---|
cryptoCode |
(required) (string) CryptoCode for the Envelope |
envelope |
(required) (string) encoded string of the transaction envelope signed by the Customer |
hash |
(string) |
cryptoCode |
(boolean) Do not verify that the envelope is already created |
Funding an account
Funding is the process of issuing new tokens and sending these to a customer's account buying the token. Payment processing is done outside of Nexus, the funding call should be done after a (when required) payment is finished successfully.
The endpoint to initiate the funding procedure is the following:
| Request | Endpoint |
|---|---|
| POST | baseURL/token/fund |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Request body (JSON)
| Key | Value |
|---|---|
customerCode |
(string) Customer identifier |
accountCode |
(float) Account identifier |
paymentMethodCode |
(float) PaymentMethod identifier |
amount |
(float) amount of stablecoin to be purchased |
tokenCode |
(string) the desired token code, e.g. "CUSD", "TEUR"... |
Depending on the token settings additional signing may be required by the designated account. This is equal to the previous steps for signing and submitting.
Execute a payment
Create payment request
To start sending tokens to another account you can initiate payment operations. The following API endpoint can be called:
| Request | Endpoint |
|---|---|
| POST | baseURL/token/payments |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Request body (JSON)
| Key | Value |
|---|---|
payments |
(array of objects) one or multiple payments, requiring the following information: - sender: (string) sender address - receiver: (string) receiving address - tokenCode: (string) the token code this transaction need to use - amount: (float) amount to be transferred |
Customer signs transaction
Once the payment request above is created, the customer needs to sign the Stellar envelope to proceed with the transfer of tokens. This can be achieved by signing it with the customer's private key, for instance by using the Stellar SDK.
Submit
Once the Stellar envelope has been signed by the customer, the transaction can be sent to Nexus by using the endpoint below.
| Request | Endpoint |
|---|---|
| POST | baseURL/token/envelope/submit |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Request body (JSON)
| Key | Value |
|---|---|
cryptoCode |
(required) (string) CryptoCode for the Envelope |
envelope |
(required) (string) encoded string of the transaction envelope signed by the Customer |
hash |
(string) |
cryptoCode |
(boolean) Do not verify that the envelope is already created |
Payout from an account
At some point, a merchant or customer will decide to cash out their tokens in exchange of fiat currency. To carry out this process, the following API endpoint can be called.
| Request | Endpoint |
|---|---|
| POST | baseURL/token/payout |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Request body (JSON)
| Key | Value |
|---|---|
accountCode |
(string) code of the source account |
paymentMethodCode |
(string) payment method to be used to transfer the fiat currency |
tokenCode |
(string) code of the token to payout |
amount |
(float) amount of token to be cashed out |
callbackUrl |
(string) callback url to receive feedback on the status of the operation |
memo |
(string) additional field to store additional information you might need |
Create a token
When a customer wants to create a new token, Nexus allows you to facilitate this process by calling the following endpoint.
| Request | Endpoint |
|---|---|
| POST | baseURL/token/tokens |
Headers
| Key | Value |
|---|---|
api_version |
(string) 1.2 |
Authorization |
(string) "Bearer " + AUTH_TOKEN (see Authentication) |
Request body (JSON)
| Key | Value | |
|---|---|---|
code |
(string) unique code of the token (required) | |
name |
(string) name of the token (required) | |
tokenType |
(string) type of the token (PeggedByCurrency / PeggedByToken / PeggedByAsset) (required) | |
assetType |
(string) asset type of the token (Native / Other) | |
rate |
(decimal) rate of the token | |
peggedBy |
(string) token/currency that pegs this token (Currency / Token / Asset) | |
settings |
token settings (as mentioned below) | |
data |
(dictionary<string,string>) optional data |
Settings
| Key | Value |
|---|---|
accountLimit |
(long) the account limit (default = null) |
overallLimit |
(long) the overall limit (default = null) |
Returnable |
(bool) can this token be returned? (default = true) |
freezeAfterFund |
(bool) freeze after fund? (default = false) |
stellarSettings |
stellar settings of the token (as mentioned below - for internal tokens only) |
StellarSettings
| Key | Value |
|---|---|
authorizationRequired |
(bool) is authorization required? (default = true) |
authorizationRevocable |
(bool) is authorization revocable? (default = true) |
authorizationImmutable |
(bool) is authorization immutable? (default = false) |
clawbackEnabled |
(bool) is clawback enabled? (default = true) |
In the case of Internal tokens, the token is created with the status = 'Active'.