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 to Merchant - the link to the site.
   3. Logo - will be displayed in the payment widget.
   4. WebHook link - URL to your Merchant Handler, where you will receive messages about successful or overdue payment.
   5. Payment time limit - the period during which the payment must be completed. Once this time expires, the payment status changes to «Expired».

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

3. For the merchant, add the wallets that will receive payments.

   1. Cryptocurrency — a digital asset that will be used to accept payments.
   2. Network — specifies the blockchain network through which payments will be processed. For example, several networks are available for USDT: TRC-20 (Tron), ERC-20 (Ethereum).

   3. Wallet address - you can use TronLink, TrustWallet or another account to create it.

      ⚠️ If your 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.

   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. Number of digits after the decimal point - limits the length 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?

      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 using many digits, e.g. 6, because it is inconvenient for users to enter amounts: $100.0000025. However, using too few digits, e.g. 1, is also not recommended - otherwise the ID amount may be too large for the user, e.g.: $100.1

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

5. 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".
6. Write handler functionality for WebHook messages.

• CryptoScan PHP Client
• Plugin for XenForo — manual in README_*.MD

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 specified network and currency 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."
            ]
        }
    }
}

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.

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.

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

Creates a request to track a transaction.

(!) 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.

(!) If the cryptocurrency and network parameters are not specified, USDT/TRC-20 will be used by default.
If the corresponding wallet does not exist or is inactive, an error will be returned.

Basic information

Query parameters

Response Parameters:

Example response:

{
    "success": true,
    "data": {
        "id": "12589",
        "final_amount": "125.69",
        "cryptocurrency": "USDT",
        "network": "TRC-20",
        "wallet": "TNVq3iEcaGWbbsR34MTdg1JMTxvYFU8Qir",
        "expire_at": "1677422490",
    }
}

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.

(!) For legacy integrations, the default mode is «USDT TRC-20 receive only», which maintains 100% backward compatibility.
When this mode is disabled, the API response will no longer include the fields wallet and final_amount.
Before disabling this mode, the integration must be updated by developers to correctly handle the new multi-currency conditions.

Basic information

Query parameters

Response Parameters:

Example response:

{
    "success": true,
    "data": {
        "id": "523654",
        "expire_at": "1677422490",
        "widget_url": "https://cryptoscan.one/payment/69908b3b-ac70-4652-9ca2-877e348a2dbe"
    }
}

Response for a merchant operating in the «USDT TRC-20 receive only» mode

{
    "success": true,
    "data": {
        "id": "523654",
        "final_amount": "133.23",
        "cryptocurrency": "USDT",
        "network": "TRC-20",
        "wallet": "TNVq3iEcaGWbbsR34MTdg1JMTxvYFU8Qir",
        "expire_at": "1677422490",
        "widget_url": "https://cryptoscan.one/payment/69908b3b-ac70-4652-9ca2-877e348a2dbe"
    }
}

Basic Information

Request parameters

Response Parameters:

Example response:

{
    "success": true,
    "data": {
        "id": 32,
        "cryptocurrency": "USDT",
        "network": "TRC-20",
        "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
    }
}

Basic information

Query parameters

Response Parameters:

Example response:

{
  "success": true,
  "data": {
    [
        {
            "id": 36,
            "cryptocurrency": "USDT",
            "network": "TRC-20",
            "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
        }
    ]
  }
}

Basic Information

Request parameters

Response Parameters:

Example response:

{
    "success": true,
    "data": {
        "id": 124,
        "wallet": null,
        "payer_wallet": "TQ5XWv7zBc9eK8yN2mQ3pR1dL4jG6fDs9x",
        "transaction_id": "b3a76a538701fd4e2a25ad9aac777f841a49f4d0",
        "source_currency": "EUR",
        "source_amount": "45.74900000",
        "final_amount": 53.8053,
        "requested_amount": 53.80526186,
        "status": "paid_manually",
        "client_reference_id": "aic03vWcrY",
        "metadata": null,
        "created_at": 1751628388,
        "paid_at": 1751890648,
        "expire_at": 1751631088
    }
}

Basic information

Response parameters:

Example response:

{
    "success": true,
    "data": {
        "id": 2,
        "status": "Active",
        "balance": 85.00,
        "currency": "USD"
    }
}

Information

Response parameters:

    {
        "success": true,
        "data": [
            {
                "currency": "BYN",
                "rate": 2.52334,
                "status": "enabled"
            },
            {
                "currency": "EUR",
                "rate": 0.93574,
                "status": "enabled"
            },
            {
                "currency": "GBP",
                "rate": 0.80534,
                "status": "disabled"
            }
        ]
    }
    

Basic information

Request parameters

Response parameters:

Example response:

{
    "success": true,
    "data": {
        "status": "enabled",
        "rate": 0.93574
    }
}