API Documentation
Step-by-step basic integration plan
- Register an account with CryptoScan.
Add a new Merchant.
- Name - the name of the site. This is the name that will be seen in the payment widget.
- URL Мерчанта - the link to the site.
- Logo - will be displayed in the payment widget.
Who pays the service commission - who will pay CryptoScan's commission: the buyer or you.
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
.USDT TRC20 wallet - you can use TronLink, TrustWallet or another account to create it.
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.
Choose the type of authentication: by private key or by signature.
- 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".
- Write handler functionality for WebHook messages.
Ready solutions for integration
- CryptoScan PHP Client
- Plugin for XenForo — manual in README_*.MD
Basic information
Terms
- User - a person who uses the current system to perform a specific function. Merchant - a User's website added to the Merchants section.
- Merchant - a User's website added to the Merchants section.
- Invoice - a request created by the User to track a payment on the TRON network within a specific Merchant.
- API User - a person who uses the API of a valid system to perform a specific function.
- 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/falsedata
- 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
- Generate a signature based on the request body and Merchant's private key
- 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:
- Sort by index in ascending order
- Encode in URL encoding
- 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:
event_type
-paid
retry_count
- number of attempts to resend the message on WebHook-
data
id
- payment IDwallet
- wallet where the payment should be made topayer_wallet
- wallet from which the payment was made.transaction_id
- transaction ID in TRON networkfinal_amount
- total amount to be paid (including "tail" and commission, if paid by the buyer).requested_amount
- amount to be paid requested by the userstatus
- payment statusclient_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 paymentcreated_at
- time of payment creation in unixtimepaid_at
- date when payment was detected in unixtimeexpire_at
- time when the invoice becomes expired (remember, we check the payment only 30 minutes after creation)
event_type
-expired
retry_count
- number of attempts to resend message to WebHook-
data
id
- payment IDwallet
- wallet to which the payment should be madefinal_amount
- total amount to be paid (including "tail" and commission, if it is paid by the buyer)requested_amount
- payment amount requested by the userstatus
- payment statusclient_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 paymentcreated_at
- time of payment creation in unixtimeexpire_at
- time when the invoice becomes expired (remember, we only check the payment 30 minutes after creation)
event_type
-paid_manually
- occurs when invoice is manually confirmedretry_count
- number of attempts to resend the message to WebHook.-
data
id
- payment IDwallet
- wallet to which payment should be madefinal_amount
- total amount to be paid (including "tail" and commission, if it is paid by the buyer)requested_amount
- payment amount requested by the userstatus
- payment statusclient_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 paymentcreated_at
- time of payment creation in unixtimeexpire_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:
|
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:
|
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:
|
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:
|
Response Parameters:
Returns |
An array of invoice objects:
|
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):
|
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:
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:
|
Example response:
{ "success": true, "data": { "status": "enabled", "rate": 0.93574 } }