API Documentation

Step-by-step basic integration plan

  1. Register an account with CryptoScan.
  2. Add a new Merchant.

    1. Name - the name of the site. This is the name that will be seen in the payment widget.
    2. URL Мерчанта - the link to the site.
    3. Logo - will be displayed in the payment widget.
    4. Who pays the service commission - who will pay CryptoScan's commission: the buyer or you.

      ⚠️ The commission will still be deducted from your balance, but the amount of the commission will be added to the amount the user must pay to be reimbursed to you.
    5. Maximum fractional digit - limits the maximum size of the fractional part of a number.

      Example numbers for value 3: 1.234, 0.789, 2.345.

      Example numbers for value 5: 1.23456, 0.98765, 2.34567.

      What is this option for?

      In the TRON network we cannot add a comment to a payment, which creates a problem of payment identification. To solve this problem, we add a unique identifier to the payment amount.

      Example: two payers (A and B) make a payment of $100 each. To distinguish which one of them paid, we add an identifier 0.003 to the payment amount of payer B. Now its amount is $100.003. If $100 is credited to the balance, it is a payment from A, and if $100.003 is a payment from B.

      We do not recommend making a large digit of the amount, e.g. 6, because it is inconvenient for users to enter amounts: $100.0000025. However, too small a digit, e.g. 1, is also not recommended - otherwise the ID amount may be too large for the user, e.g.: $100.1

    6. USDT TRC20 wallet - you can use TronLink, TrustWallet or another account to create it.

      ⚠️ If your USDT TRC20 wallet has a large flow of incoming transactions, we recommend you to create a separate wallet for our service. This will help to avoid errors when detecting transactions: CryptoScan may misinterpret third-party transactions as payment of your invoices.
    7. WebHook link - URL to your Merchant Handler, where you will receive messages about successful or overdue payment.

      After creating a Merchant - you will have keys available to work with the API.

  3. Choose the type of authentication: by private key or by signature.

  4. Write the functionality of payment creation in your application. You can use our solution to interact with API. To create a payment with our widget - use the API method "Create widget for Invoice". If you want to make your own payment widget - use "Create Invoice widget".
  5. Write handler functionality for WebHook messages.

Ready solutions for integration

Basic information

Terms

  1. User - a person who uses the current system to perform a specific function. Merchant - a User's website added to the Merchants section.
  2. Merchant - a User's website added to the Merchants section.
  3. Invoice - a request created by the User to track a payment on the TRON network within a specific Merchant.
  4. API User - a person who uses the API of a valid system to perform a specific function.
  5. Payer - a person who must pay the Invoice created for him/her.

Request

Base URL: https://cryptoscan.one/api/v1

Response body:

  • success - flag, depending on the success of the request - contains true/false
  • data - contains the result of the request execution. If the request is unsuccessful - returns error information

Successful request:

{
    "success": true,
    "data": {
        "property": "value",
        "second_property": "second_value"
    }
}

Requests with an error:

{
    "success": false,
    "data": {
        "name": "Unauthorized",
        "message" : "Your request was made with invalid credentials",
        "code": 0,
        "status": 401
    }
}

This answer includes a list of errors in the errors property:

{
    "success": false,
    "data": {
        "message": "Invalid request data",
        "errors": {
            "amount": [
                "Amount cannot be blank."
            ],
            "client_reference_id": [
                "Client Reference Id cannot be blank."
            ]
        }
    }
}
* The message parameter may not be specified

Authentication

There are two types of authentication - by private key or via request signature. The authentication method is switched in the settings.

For either type of authentication, you must pass Merchant's public key in the header: public-key.

Authentication by private key

Pass Merchant's private key in the HTTP header private-key.

This method is easier to integrate, but less secure because the private key must be transmitted over the Web.

Authentication by signature
  1. Generate a signature based on the request body and Merchant's private key
  2. Pass the signature via HTTP signature header

This method is more difficult to integrate and test than signature, but is more reliable because the private key is not transmitted over the Web.

(!) Treat the private key as a password. Do not share it with third parties.

Signature generation

The signature is used to authenticate WebHook messages and API requests when authenticating by signature. SHA-256 hashing is used for this purpose.

To generate a signature, it is necessary to perform the following actions on the request parameters:

  1. Sort by index in ascending order
  2. Encode in URL encoding
  3. Hash using SHA-256 HMAC algorithm, use Merchant's private key as a secret key.

An example of creating a signature in PHP:

$requestBody['api_key'] = $publicKey;
ksort($requestBody);
$signature = hash_hmac('sha256', http_build_query($requestBody), $privateKey);

To pass the signature to the request, add it to the HTTP header of the signature request.

The API request is also passed a public key, which the system uses to find the Merchant. Then using the Merchant's private key, which is set by the API User in the Merchants section, the system hashes the request body data to create a similar signature on its side. If the signature received in the API request is identical to the signature generated on the server side, it means that the API User has been authenticated.

Response format

Available formats: JSON, XML. The format is determined depending on the contents of the Accept property in the request header.

Format for JSON:

Accept: application/json

Format for XML:

Accept: application/xml

You can define the response regardless of the header by using the _format GET parameter.
Example: _format=json

Webhook

Webhook - a procedure for sending a notification to your server when a certain Invoice event occurs.
After overdue or successful payment, the system will send a notification to this URL.

A Webhook is considered successfully delivered if your server returned HTTP code = 200.
In case of unsuccessful delivery, the system provides for WebHook resends, which are are sent at the following intervals:

  • Request #1: immediately after payment
  • Request #2: 30 seconds
  • Request #3: 2 minutes
  • Request #4: 10 minutes
  • Request #5: 60 minutes
  • Request #6: 2 hours
  • Request #7: 4 hours
  • Request #8: 6 hours
  • Request #9: 12 hours
  • Request #10: 24 hours

After the 10th request - new ones are no longer sent. Also after successful delivery - further notifications are not sent.

Each response from your server to a Webhook message is saved and can be viewed in the invoice section. The response header and its content trimmed to 5000 characters is specified.

Message Types on WebHook:
Successful payment
  • event_type - paid
  • retry_count - number of attempts to resend the message on WebHook
  • data
    • id - payment ID
    • wallet - wallet where the payment should be made to
    • payer_wallet - wallet from which the payment was made.
    • transaction_id - transaction ID in TRON network
    • final_amount - total amount to be paid (including "tail" and commission, if paid by the buyer).
    • requested_amount - amount to be paid requested by the user
    • status - payment status
    • client_reference_id- payment number in the API User's system. It must be unique for each Invoice within Merchant.
    • metadata- arbitrary string specified by the user when creating the payment
    • created_at - time of payment creation in unixtime
    • paid_at - date when payment was detected in unixtime
    • expire_at - time when the invoice becomes expired (remember, we check the payment only 30 minutes after creation)
Payment expired
  • event_type - expired
  • retry_count - number of attempts to resend message to WebHook
  • data
    • id - payment ID
    • wallet - wallet to which the payment should be made
    • final_amount - total amount to be paid (including "tail" and commission, if it is paid by the buyer)
    • requested_amount - payment amount requested by the user
    • status - payment status
    • client_reference_id - payment number in the API User's system. It must be unique for each Invoice within Merchant.
    • metadata - arbitrary string specified by the user when creating the payment
    • created_at - time of payment creation in unixtime
    • expire_at - time when the invoice becomes expired (remember, we only check the payment 30 minutes after creation)
Payment confirmed manually
  • event_type - paid_manually - occurs when invoice is manually confirmed
  • retry_count - number of attempts to resend the message to WebHook.
  • data
    • id - payment ID
    • wallet - wallet to which payment should be made
    • final_amount - total amount to be paid (including "tail" and commission, if it is paid by the buyer)
    • requested_amount - payment amount requested by the user
    • status - payment status
    • client_reference_id - payment number in the API User's system. It must be unique for each Invoice within Merchant.
    • metadata - arbitrary string specified by the user when creating the payment
    • created_at - time of payment creation in unixtime
    • expire_at - time when the invoice becomes expired (remember, we only check the payment 30 minutes after creation)

Creating an Invoice

Creates a request to track a transaction in the TRON network.

(!) Using this API method, the API User needs to independently output data for the Payer: details, amount, payment term. If you don't want to make your own payment widget - use ours.

Basic information
Method POST invoice
Example URL https://cryptoscan.one/api/v1/invoice
Query parameters
Parameter name Data type Obligatory Description
amount float + Amount payable
currency string Currency of the amount payable, which is specified by the User. If this parameter is not set, the amount is considered to be in US dollars by default. You can find out the available currencies and their rates in the Currency rate section.
client_reference_id string + Payment number in the API User's system. Must be unique for each Invoice within the Merchant.
metadata string Random string up to 2000 characters.
Response Parameters:
Returns

Invoice Object:

id invoice ID
final_amount payment amount
wallet Wallet where the payment should be made to
expire_at Time in unixtime, when the payment will become overdue (remember, our system checks the payment only 30 minutes after creation).
Example answer:
{
    "success": true,
    "data": {
        "id": "12589",
        "final_amount": "125.69",
        "wallet": "TNVq3iEcaGWbbsR34MTdg1JMTxvYFU8Qir",
        "expire_at": "1677422490",
    }
}

Creating a Widget for Invoice

In addition to creating a payment invoice, this request creates a widget page and returns a URL to it. By navigating to this page, the Payer can make the payment.

Basic information
Method POST invoice/widget
Example URL https://cryptoscan.one/api/v1/invoice/widget
Query parameters
Parameter name Data type Obligatory Description
amount float + Payment amount
currency string Currency of the payment amount specified by the User. If this parameter is not specified, by default the amount is considered to be in US dollars.
client_reference_id string + Payment number in the User's API system. Must be unique for each Invoice within Merchant.
widget_description string Description that the Payer will see on the payment page up to 100 characters
metadata string Arbitrary string specified by the user when creating the payment
back_url string URL where the user will be redirected to after payment
cancel_url string URL where the user will be redirected to in case of payment cancellation
lang string Widget language (ru-RU, en-EN)
Response Parameters:
Returns

The object of the invoice widget:

id Invoice ID
final_amount Total amount payable
wallet Wallet where the payment should be made to
expire_at Time in unixtime, when the payment will become overdue (remember, our system checks the payment only 30 minutes after creation).
widget_url URL of the widget page where the Payer will go to pay the invoice.
Example response:
{
    "success": true,
    "data": {
        "id": "523654",
        "final_amount": "133.23",
        "wallet": "TNVq3iEcaGWbbsR34MTdg1JMTxvYFU8Qir",
        "expire_at": "1677422490",
        "widget_url": "https://cryptoscan.one/payment/69908b3b-ac70-4652-9ca2-877e348a2dbe"
    }
}

View Invoice

Basic Information
Method GET invoice
Example URL https://cryptoscan.one/api/v1/invoice/1
Request parameters
Parameter Name Data type Obligatory Description
id integer + Invoice ID
Response Parameters:
Returns

Invoice object:

id Invoice ID
wallet Wallet where the payment should be made to
payer_wallet Wallet from which the payment was made
transaction_id Transaction ID in TRON network
source_currency Currency specified by the User
final_amount Total amount to be paid
requested_amount Requested amount to be paid
status Payment Status
client_reference_id Payment number in the API User's system. Must be unique for each Invoice within Merchant.
metadata Arbitrary string specified by the user when creating a payment
created_at Payment creation time in unixtime
paid_at Payment discovery date in unixtime
expire_at Time in unixtime when the payment will become delinquent (remember, our system only checks the payment 30 minutes after creation)
Example answer:
{
    "success": true,
    "data": {
        "id": 32,
        "wallet": "TBjkHCYgMb1ohJq77aovAyw4kCMtBEtMGN",
        "payer_wallet": null,
        "transaction_id": null,
        "final_amount": 10.54,
        "requested_amount": "10.54",
        "status": "completed",
        "client_reference_id": "287",
        "metadata": null,
        "created_at": 1678991717,
        "paid_at": null,
        "expire_at": 1678993517
    }
}

Invoice Search

Basic information
Method GET invoice
Example URL https://cryptoscan.one/api/v1/invoice?query=123456789
Query parameters
Parameter name Data type Obligatory Description
query string + The value to search for invoices. The following fields will be searched for the specified value:
  • id - Invoice ID
  • client_reference_id - Payment number in the API User's system. Must be unique for each Invoice within Merchant.
  • transaction_id - Transaction ID in TRON network
Response Parameters:
Returns

An array of invoice objects:

id Invoice ID
wallet Wallet where the payment should be made to
payer_wallet Wallet from which the payment was made
transaction_id Transaction ID in TRON network
source_currency Currency specified by the User
final_amount Total amount to be paid
requested_amount Requested amount to be paid
status Payment Status
client_reference_id Payment number in the User's API system. Must be unique for each Invoice within Merchant.
metadata Arbitrary string specified by the user when creating a payment
created_at Payment creation time in unixtime
paid_at Date the payment was detected in unixtime
expire_at Time in unixtime when the payment will become delinquent (remember, our system only checks the payment 30 minutes after creation)
Example response:
{
  "success": true,
  "data": {
    [
        {
            "id": 36,
            "wallet": "TNVq3iEcaGWbbsR34MTdg1JMTxvYFU8Qir",
            "payer_wallet": "TNVq3iEcaGWbbsR34MTdg1JMTxvYFU8Qir",
            "transaction_id": "1234567890",
            "final_amount": 6.5,
            "requested_amount": "6.50000000",
            "status": "new",
            "client_reference_id": "539",
            "metadata": null,
            "created_at": 1679584937,
            "paid_at": 1679585937,
            "expire_at": 1679586737
        }
    ]
  }
}

View information about the user (yourself)

basic information
Method GET user
Example URL https://cryptoscan.one/api/v1/user
Response parameters:
Returns

A data object about the user (self):

id User ID
status Status
balance Current balance
currency Currency
Example response:
{
    "success": true,
    "data": {
        "id": 2,
        "status": "Active",
        "balance": 85.00,
        "currency": "USD"
    }
}

Supported currencies

Information
Method GET currency-rate
Example URL https://cryptoscan.one/api/v1/currency-rate
Response parameters:
Returns

An array of exchange rate objects:

currency The currency code in ISO 4217, for example: EUR
rate Currency rate against the US dollar (USD)
status Currency status. Can have the following values:
  • enabled - Available
  • disabled - Not available
Example answer:
    {
        "success": true,
        "data": [
            {
                "currency": "BYN",
                "rate": 2.52334,
                "status": "enabled"
            },
            {
                "currency": "EUR",
                "rate": 0.93574,
                "status": "enabled"
            },
            {
                "currency": "GBP",
                "rate": 0.80534,
                "status": "disabled"
            }
        ]
    }
    

Currency availability check

Basic information
Method GET currency-rate/status
Example URL https://cryptoscan.one/api/v1/currency-rate/GBP/status
Request parameters
Parameter name Data type Mandatory Description
currency string + ISO 4217 currency code to be checked for availability, e.g.: EUR
Response parameters:
Returns

The status of the exchange rate:

status The status of the currency. Can take the following values:
  • enabled - Currency on.
  • disabled - Currency off.
  • not_supported - Currency does not exist or is not supported.
rate The currency rate against the United States dollar (USD). If the currency being checked is not supported (not_supported), returns the value null
Example response:
{
    "success": true,
    "data": {
        "status": "enabled",
        "rate": 0.93574
    }
}