Creating a Pay-in Request
This endpoint allows you to create a new payment link and receive a URL that can be used to complete the accept a crypto payment from your customer. By sending a request to this endpoint with the required parameters, you can generate a payment link for a specific amount and configure various payment options.
Endpoint
POSThttps://api.tylt.money/transactions/merchant/createPayinRequest
Request Headers
X-TLP-APIKEY
string
93ee3c5e133697251b5362bcf9cc8532476785t8768075616f58d88
Your Tylt API Key, used to identify your account in API requests.
X-TLP-SIGNATURE
string
d0afef3853dfc8489c8b9affa5825171fdd7y7685675e4966a05f66ed2b3eaf9462b3c9c0
HMAC SHA-256 signature generated using the API Secret Key to secure the request.
Request Body
Field Name
Type
Description
merchantOrderId
string
The order ID provided by the Merchant for local reference.
baseAmount
number
The amount to be paid.
baseCurrency
string
The base currency of the good/service being supplied.
settledCurrency
string
The currency in which the payment is to be made.
networkSymbol
string
The network symbol for the transaction (e.g., BSC).
callBackUrl
string
URL for the callback after transaction completion.
customerName
string
Optional: Customer's name for the transaction.
comments
string
Optional: Comments for additional context.
settleUnderpayment
number
This parameter determines how the system handles underpayments — cases where the customer pays less than the expected amount.
If settleUnderpayment = 1 (Default):
The transaction will be automatically settled, even if the customer sends less than the required amount.
No further payment is expected.
The merchant assumes responsibility for accepting the shortfall. Refer settledAmountReceived and baseAmountRecieved via the webhook to handle business logic.
If settleUnderpayment = 0:
The transaction will remain unsettled until the full expected amount is received.
The customer must complete the remaining payment before the payment intent expires.
If the full amount is not received by the expiry time, the payment intent will expire, and the transaction will Be settled as underpayment. Refer settledAmountReceived and baseAmountRecieved via the webhook to handle business logic.
Code Snippet
const axios = require('axios');
const crypto = require('crypto');
// Replace with your API Key and Secret
const apiKey = 'your-api-key';
const apiSecret = 'your-api-secret';
// Request body
const requestBody = {
merchantOrderId: 'b73b73b-87wtbc-q36gbc-331n3',
baseAmount: '1',
baseCurrency: 'USDT',
settledCurrency: 'USDT',
networkSymbol: 'BSC',
callBackUrl: 'https://www.test.com/callback',
customerName: 'TradingLeagues',
comments: 'Description testing'
};
// Convert request body to JSON
const raw = JSON.stringify(requestBody);
// Function to create HMAC SHA-256 signature
const createSignature = (secret, data) => {
return crypto.createHmac('sha256', secret)
.update(data)
.digest('hex');
};
// Generate signature
const signature = createSignature(apiSecret, raw);
// Define headers
const headers = {
"X-TLP-APIKEY": apiKey,
"X-TLP-SIGNATURE": signature
};
// Send the request
axios.post('https://api.tylt.money/transactions/merchant/createPayinRequest', raw, { headers })
.then(response => console.log("Success:", response.data))
.catch(error => console.error("Error:", error));
import requests
import hmac
import hashlib
import json
# Replace with your API Key and Secret
api_key = 'your-api-key'
api_secret = 'your-api-secret'
# Request body
request_body = {
"merchantOrderId": "b73b73b-87wtbc-q36gbc-331n3",
"baseAmount": "1",
"baseCurrency": "USDT",
"settledCurrency": "USDT",
"networkSymbol": "BSC",
"callBackUrl": "https://www.test.com/callback",
"customerName": "TradingLeagues",
"comments": "Description testing"
}
# Convert request body to JSON
raw = json.dumps(request_body, separators=(',', ':'), ensure_ascii=False)
# Function to create HMAC SHA-256 signature
def create_signature(secret, data):
return hmac.new(secret.encode(), data.encode(), hashlib.sha256).hexdigest()
# Generate signature
signature = create_signature(api_secret, raw)
# Define headers
headers = {
"Content-Type": "application/json",
"X-TLP-APIKEY": api_key,
"X-TLP-SIGNATURE": signature
}
# Send the request
response = requests.post('https://api.tylt.money/transactions/merchant/createPayinRequest', headers=headers, data=raw)
print("Response:", response.json())
const fetch = require('node-fetch');
const crypto = require('crypto');
// Replace with your API Key and Secret
const apiKey = 'your-api-key';
const apiSecret = 'your-api-secret';
// Request body
const requestBody = {
merchantOrderId: 'b73b73b-87wtbc-q36gbc-331n3',
baseAmount: '1',
baseCurrency: 'USDT',
settledCurrency: 'USDT',
networkSymbol: 'BSC',
callBackUrl: 'https://www.test.com/callback',
customerName: 'TradingLeagues',
comments: 'Description testing'
};
// Convert request body to JSON
const raw = JSON.stringify(requestBody);
// Function to create HMAC SHA-256 signature
const createSignature = (secret, data) => {
return crypto.createHmac('sha256', secret)
.update(data)
.digest('hex');
};
// Generate signature
const signature = createSignature(apiSecret, raw);
// Define headers
const headers = {
"Content-Type": "application/json",
"X-TLP-APIKEY": apiKey,
"X-TLP-SIGNATURE": signature
};
// Function to send the request
const sendRequest = async (url, headers, body) => {
const response = await fetch(url, {
method: 'POST',
headers: headers,
body: body,
});
return response.json();
};
// Send the request
sendRequest('https://api.tylt.money/transactions/merchant/createPayinRequest', headers, raw)
.then(result => console.log("Success:", result))
.catch(error => console.error("Error:", error));
Response
{
"data": {
"orderId": "d0d6ff5f-79b6-11ef-8277-02d8461243e9",
"merchantOrderId": "b73b73b-87wtbc-q36gbc-331n3",
"baseAmount": 1,
"baseCurrency": "USDT",
"settledCurrency": "USDT",
"settledAmountRequested": 1,
"settledAmountReceived": 0,
"settledAmountCredited": 0,
"commission":0.01,
"network": "BSC",
"depositAddress": "0xbfae84b277c5b791206a58f634b88527287bf2f8",
"status": "Pending",
"paymentURL": "https://app.tylt.money/pscreen/d0d6ff5f-79b6-11ef-8277-02d8461243e9",
"callBackURL": "",
"transactions": [],
"createdAt": "2024-09-23T14:19:16Z",
"expiresAt": "2024-09-23T15:19:16Z",
"updatedAt": "2024-09-23T14:19:16Z",
"isFinal": 0,
"isCredited": 0,
"customerName": "TradingLeagues",
"comments": "Description testing 234"
},
"msg": ""
}Field Name
Type
Description
orderId
string
The order ID generated by TL Pay.
merchantOrderId
string
The order ID provided by the Merchant at the time of request.
baseAmount
number
The value of the good/service being supplied expressed in the baseCurrency
baseCurrency
string
The base currency of the good/service. (symbol)
settledCurrency
string
The crypto currency in which the payment is to be made by the customer. (symbol)
settledAmountRequested
number
The amount of crypto currency requested from the customer.
settledAmountReceived
number
The amount of crypto currency received from the customer.
settledAmountCredited
number
The amount of crypto currency credited to your balance.
commission
number
The commission deducted for the transaction.
network
string
The crypto network used for the payment.
depositAddress
string
The address where the payment should be sent by the customer.
status
string
The status of the transaction (e.g., Pending, Completed).
paymentURL
string
The URL for the customer to make the payment.
callBackURL
string
The URL for callback notifications.
transactions
array
Details of the transactions associated with the payment.
createdAt
string
The timestamp when the request was created.
expiresAt
string
The timestamp when the request expires.
updatedAt
string
The timestamp when the request was last updated.
isFinal
number
Indicates if the transaction is completed (1) or pending (0).
isCredited
number
Indicates if the payment has been credited (1) or not (0).
customerName
string
The name of the customer making the payment.
comments
string
Additional comments provided during the request.
Understanding BaseCurrency and SettledCurrency in Pay-In Requests
The baseCurrency represents the currency in which the merchant expects to receive the payment, while the settledCurrency refers to the currency in which the transaction is processed and settled.
Example 1:
A merchant sells a pair of shoes on an e-commerce website, priced at $100. The merchant accepts payments in cryptocurrency, and the customer chooses to pay using DAI.
baseCurrency: USD (the currency the merchant prices the shoes in)
settledCurrency: DAI (on Binance Smart Chain or another supported network)
In this case, the merchant expects $100 in USD, but the transaction will be processed in DAI on the BSC network. The merchant will receive the equivalent amount of DAI, calculated automatically by Tylt based on real-time spot rates at the time of the transaction request.
Example 2:
The baseCurrency doesn't have to be a fiat currency (USD, GBP, EUR, etc.). It can also be a cryptocurrency.
For instance, a merchant providing consulting services charges $100 in USDT.
If the customer chooses to pay in USDT, both the baseCurrency and settledCurrency will be USDT.
If the customer opts to pay in DAI, the baseCurrency will be USDT, and the settledCurrency will be DAI.
This scenario shows that both the baseCurrency and settledCurrency can be cryptocurrencies, and Tylt will handle the correct conversion at the moment of the transaction using real-time rates.