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

First Tab

Name	Type	Example	Description
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.

When using the API, ensure to include your API Key and generate the signature for the request payload using your API Secret. The tables provided above contain example values for illustration purposes only. Please refer to the code snippets for detailed instructions on how to sign the request and generate the signature properly.

Request Body

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.
redirectUrl	string	URL to redirect the user after completing the payment.
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.
payeeDetails	json Object	Mandatory object containing Travel Rule data for the transaction originator, required for AML/CFT compliance. Structure varies by entityType. entityType Specifies originator type: individual or company. individual Required if entityType = individual. =========================== firstName, lastName, DOB (YYYY-MM-DD), placeOfBirth company Required if entityType = company. =========================== fullName, "address": { "country": "DEU", "town": "Berlin", "postCode": "10115", "street": "Chauseestr.", "buildingNumber": "60" }

Code Snippet

JavaScript (Axios)

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',
    redirectUrl: 'httpsL//www.test.com/homepage',
    customerName: 'TradingLeagues',
    comments: 'Description testing'
    payeeDetails: {
        entityType: 'induvidual'
        firstName: 'Jon Smith'
        lastName: 'Doe',
        DOB: '1999-09-23'
        placeOfBirth: 'Germany'
    }
        payeeDetails: {
          entityType: 'company'
          fullName: "ACME Corp",
          address: {
          country": 'Germany',
          town: 'Berlin',
          postCode: '10115,
          street: "Chauseestr.",
          buildingNumber: "60"
    }
    
};

// 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
};

// 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));

Python

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
{
  "merchantOrderId": "b73b73b-87wtbc-q36gbc-331n3",
  "baseAmount": "1",
  "baseCurrency": "USDT",
  "settledCurrency": "USDT",
  "networkSymbol": "BSC",
  "callBackUrl": "https://www.test.com/callback",
  "customerName": "TradingLeagues",
  "comments": "Description testing",
  "payeeDetails": {
    "entityType": "individual",
    "firstName": "Jon",
    "lastName": "Doe",
    "dateOfBirth": "1999-09-23",
    "placeOfBirth": "Germany"
  },
   "payeeDetails": {
    "entityType": "company",
    "fullName": "ACME Corp",
    "registrationNumber": "HRB123456",
    "address": {
      "country": "DEU",
      "town": "Berlin",
      "postCode": "10115",
      "street": "Chauseestr.",
      "buildingNumber": "60"
    }
}

# 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())

JavaScript (Fetch)

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',
    payeeDetails: {
        entityType: 'induvidual'
        firstName: 'Jon Smith'
        lastName: 'Doe',
        DOB: '1999-09-23'
        placeOfBirth: 'Germany'
    }
        payeeDetails: {
          entityType: 'induvidual'
          fullName: "ACME Corp",
          address: {
          country": 'Germany',
          town: 'Berlin',
          postCode: '10115,
          street: "Chauseestr.",
          buildingNumber: "60"
    }
};

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

200

{
    "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": "",
        "redirectURL":"",
        "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": ""
}

Response Fields

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.

Important Notes:

The baseCurrency can be either a supported fiat or cryptocurrency. The settledCurrency will always be a cryptocurrency.