How to use
These documents have been collected for your ease of use of Pay to Moon services and describe how to make electronic payments on the web from online stores using the payToMoon payment portal. Additionally, explore our innovative WebsiteLess deposit feature for businesses without websites, simplifying cryptocurrency transactions with a one-time payment link creation.
PayToMoon offers a convenient platform for buyers to make payments using cryptocurrencies. The scope of this documentation is to explain how providers connect their payment gateway to PayToMoon and offer a comprehensive overview of the procedures required to execute payment transactions. Additionally, it outlines all associated methods relevant to facilitating these transactions.
Technical information
Our APIs are RESTful and requests and responses are exchanged as JSON.
The status code of all successful requests is 200, all invalid requests are 400, and internal server errors are 500.
Our response values adhere to a standardized structure. If the value of StatusCode is equal to 50, the operation has been successfully completed, otherwise, an error has occurred and you can find the reason for the error according to the code returned in StatusCode in the list of errors. The return information of each method will be placed inside the Message.
{
isSuccess : true,
statusCode : 50,
message : {}
}
The cryptocurrencies that we support in payment operations and through which buyers can make their payment operations.
Name | Id |
---|---|
Dogecoin (DOGE) | DOGE |
Tron (TRX) | TRX |
The currencies of the countries that we support in payment operations which we will convert them to desired cryptocurrency and through which buyers can make their payment operations
Name | Id |
---|---|
United States Dollar (USD) | USD |
European Union countries (EUR) | EUR |
Pound sterling (GBP) | GBP |
Japanese Yen (JPY) | JPY |
Australian Dollar (AUD) | AUD |
Brazilian Real (BRL) | BRL |
Russian Ruble (RUB) | RUB |
Turkish lira (TRY) | TRY |
Iranian Rial (IRT) | IRT |
API documentation
To utilize the PayToMoon web service, it is imperative to employ the specified web service addresses, methods, and parameters provided.
1 - Authentication
PayToMoon uses the Application Id, Nonce and Signature headers to authenticate requests. //In this way, all your requests
//must contain the following header:
{
"applicationId": { YourApplicationId }
"nonce": { Nonce }
"signature": { Signature }
}
//In this way, all your requests
//must contain the following header:
{
"applicationId": { YourApplicationId }
"nonce": { Nonce }
"signature": { Signature }
}
How to get ApplicationId ?
By referring to the your profile and account section, copy the Application Id
How to create Nonce ?
To create a Nonce, just create a ten-digit random number and combine it with the current Time Stamp. (write the ten-digit number first and paste the current time stamp at the end)
function createNonce() {
const random_number = Math.floor(Math.random() * 1000000000) + 1;
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = random_number + timestamp;
return nonce;
}
How to create Signature ?
You need your generated Secret Key and Nonce to create a Signature.
The HMAC algorithm is used with the SHA-256 hash algorithm to create a cryptographic signature. To do this, apply the HMAC-SHA256 algorithm to the nonce using the Secret Key as the key and create the HMAC-SHA256 signature.
Then encode your HMAC-SHA256 signature to base64 format. This step ensures that the signature is displayed as a string of printable ASCII characters.
import crypto from 'crypto'
function createSignature(nonce, secretKey) {
const hmacHash = crypto.createHmac('sha256', secretKey).update(nonce).digest('base64');
return hmacHash;
}
2 - Create deposit
You can use this endpoint to register a deposit and receive Access Token to transfer the user to the paytomoon payment page.
Note: The blockchain network fee will be deducted from the Source Token Amount
Note: The provider themselves can execute the conversion of monetary units to cryptocurrency. In this scenario, it's crucial that both SourceToken and DestinationToken values represent cryptocurrencies, ensuring that PayToMoon abstains from performing the conversion operation.
async function requestForDeposit(apiKey, secretKey, applicationId) {
const nonce = createNonce();
const signature = createSignature(nonce, secretKey);
const requestBody = {
callBackUrl: 'YOUR_CALL_BACK_URL', // example https://test.com
description: 'test',
apiKey: apiKey,
orderId: '<YOUR_ORDER_ID>',
sourceToken: 'DOGE',
destinationToken: 'DOGE',
sourceTokenAmount: 1000
};
const headers = {
'Content-Type': 'application/json',
'ApplicationId': applicationId,
'Nonce': nonce,
'Signature': signature
};
const url = 'https://ptm.paytomoon.com/api/v1/Client/deposit/request';
try {
const response = await axios.post(url, requestBody, { headers: headers });
const responseData = response.data;
console.log(responseData);
if (responseData.isSuccess && responseData.statusCode === 50) {
const accessToken = responseData.data.accessToken;
return accessToken;
} else {
console.log('Deposit request failed.');
return null;
}
} catch (error) {
console.log('Error making deposit request:', error);
return null;
}
}
Request body
Params name | Type | Is required | Description |
---|---|---|---|
apiKey | String | true | One of your gate Api key. you can copy it from profile/gates |
callBackUrl | String | true | The buyer's return page, after making the payment |
orderId | String | false | The order number that the provider has generated to track their orders and we return it to the provider when the provider calls the Verify method. |
sourceToken | String | true | Cryptocurrency or currency of the country we support |
sourceTokenAmount | Decimal | true | The amount of cryptocurrency or monetary unit that the buyer will pay to the provider |
destinationToken | String | true | The cryptocurrency into which the buyer's currency amount will be converted and subsequently transferred to the provider's wallet. |
description | String | false | Description of the transaction |
// request body example
{
"apiKey" : "<YOUR_API_KEY>",
"callBackUrl" : "https://www.example.com/example",
"sourceToken" : "usd",
"sourceTokenAmount" : "2500",
"destinationToken" : "DOGE",
"destinationNetwork" : "DOGE",
}
// response example
{
"isSuccess" : true,
"statusCode" : 50,
"message" : {
"accessToken" : "ACCESS_TOKEN"
}
}
3 - Redirect
Redirecting the user to the PayToMoon payment page.
After successfully completing the deposit registration operation, if the StatusCode of the response matches 'Success' and the required data is retrieved, the provider is required to redirect the buyer to the PayToMoon payment page. To achieve this, the provider should append the received data to the end of the following URL and direct the user to the resulting link, thereby facilitating immediate access to the PayToMoon payment gateway.
Note: From the time of sending the user to payToMoon, the buyer has 120 minutes to make the payment in the payToMoon payment portal, otherwise the data will expire.
https://paytomoon.com/portal/crypto/<ACCESS_TOKEN>
4 - Return to the provider site
Once the buyer's payment process is concluded on PayToMoon, it is PayToMoon's responsibility to redirect the buyer back to the designated provider's site specified by the CallbackURL.
Note: When returning the buyer to the provider site, a Status is sent to the provider site in the form of QueryString, which has four fixed values: "SUCCESS", "FAIL", "CANCEL" and "EXPIRE"; If this value is equal to "FAIL", it means that the transaction was unsuccessful, if this value is equal to "CANCEL", it means that the transaction was canceled by the buyer, and if this value is equal to " "Expire" means that no transaction has been done; So, verify is used if the Status value is equal to "SUCCESS" with QueryString.
Note: When returning the buyer to the provider site, in addition to the Status, AccessToken and OrderId are also sent to the provider site. AccessToken is the unique identifier with which the provider party redirected the buyer to the PayToMoon payment page.
//example if your call back url is:
https://www.test.com/verify
https://www.test.com/verify?accessToken=<ACCESS_TOKEN>&status=<STATUS>&orderId=<ORDER_ID>
5 - Verify
You can leverage this API to check out the buyer's payment status and receive a reference to follow up.
const axios = require('axios');
const crypto = require('crypto');
function createNonce() {
const random_number = Math.floor(Math.random() * 1000000000) + 1;
const timestamp = Math.floor(Date.now() / 1000);
const nonce = random_number.toString() + timestamp.toString();
return nonce;
}
function createSignature(nonce, secret_key) {
const signature = crypto.createHmac('sha256', secret_key)
.update(nonce)
.digest('base64');
return signature;
}
async function getDepositState(api_key, secret_key, application_id) {
const nonce = createNonce();
const signature = createSignature(nonce, secret_key);
const request_body = {
apiKey: api_key,
accessToken: "YOUR_DEPOSIT_ACCESS_TOKEN",
};
const headers = {
"Content-Type": "application/json",
"ApplicationId": application_id,
"Nonce": nonce,
"Signature": signature,
};
const url = "https://ptm.paytomoon.com/api/v1/Client/deposit/verify";
try {
const response = await axios.post(url, request_body, { headers });
const response_data = response.data;
console.log(response_data);
if (response_data.isSuccess && response_data.statusCode === 50) {
const deposit_state = response_data.data.stateOfDeposit;
return deposit_state;
} else {
console.log("Deposit request failed.");
return null;
}
} catch (error) {
console.log(error);
return null;
}
}
// Example usage
const api_key = "YOUR_API_KEY";
const secret_key = "YOUR_SECRET_KEY";
const application_id = "YOUR_APPLICATION_ID";
getDepositState(api_key, secret_key, application_id)
.then(deposit_state => {
if (deposit_state) {
console.log(deposit_state);
} else {
console.log("Verify request unsuccessful.");
}
});
Response body
Params name | Type | Description |
---|---|---|
stateOfDeposit | String | Buyer's payment status, which are: 'Success', 'Pending', 'Expire', 'Fail', 'Cancel' |
depositReference | String | Transaction number (a 36-character special code for each payment that we return to the provider in order to track the payment) |
orderId | String | The order number that the provider has generated to track their orders and sent to us when calling the Request method |
//POST
{baseURL}/Client/deposit/verify
//request payload
{
"apiKey": "string",
"accessToken": "string"
}
//response
{
"isSuccess" : true,
"statusCode" : 50,
"message" :
{
"stateOfDeposit" : "Success" | "Cancel" | "Fail" | "Expire" | "Pending" ,
"depositReference" : "string" ,
"orderId" : "string"
}
}
Summary of the buyer's purchase process
The buyer selects products or services on the provider's website and is prepared to pay the invoice amount.
The provider submits the request details to PayToMoon using the Create Deposit method. In response, PayToMoon sends the AccessToken and request status (StatusCode). If successful, the provider redirects the buyer to the PayToMoon payment portal page.
After completing the payment process on PayToMoon, the buyer will be redirected back to the provider's site via the CallbackURL.
On the CallbackURL page, the provider locates a request matching the AccessToken sent by PayToMoon as a QueryString. The provider checks the transaction status (Status) using the Verify method. If successful, the provider records the payment and displays the transaction number (Reference) to the buyer. Otherwise, the provider notifies the buyer of any errors based on the received error code from the Verify method.
Errors
The errors that may occur are as follows
Code | Description |
---|---|
50 | The operation has been successfully completed |
51 | There is a problem with PayToMoon |
52 | The length of the input exceeds the limit |
53 | Fields are mandatory |
54 | Application Id not found |
55 | Duplicate Nonce error |
56 | Nonce is invalid |
57 | Signature is mandatory |
58 | Signature is wrong |
59 | Signature is invalid |
60 | The source cryptocurrency or currency of the imported source country is not supported |
61 | The destination cryptocurrency entered is not supported |
62 | An error has occurred from the Provider side |
63 | The desired deposit was not found |
64 | Deposit Bad State |
65 | The amount of the deposit is less than the minimum deposit |
66 | The requested deposit has expired |
67 | User not found |
68 | The user is Ben |
69 | The desired gate was not found |
70 | The desired gate is disabled |
71 | Order Id is repeated deposit |
72 | This IP is not allowed to use the desired gate |
73 | A calculation error occurred |
74 | An error occurred while retrieving prices |
75 | An error occurred while calculating the balance |
76 | Access denied |
77 | The number of requests exceeds the limit |
78 | Imported cryptocurrency is not supported |
79 | The gateway that has IP restrictions should specify the allowed IPs |