# 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**

<mark style="color:green;">**`POST`**</mark>`https://api.tylt.money/transactions/merchant/createPayinRequest`

**Request Headers**

{% tabs %}
{% tab title="First Tab" %}

<table data-full-width="true"><thead><tr><th width="133">Name</th><th width="79">Type</th><th width="167">Example</th><th>Description</th></tr></thead><tbody><tr><td>X-TLP-APIKEY</td><td>string</td><td>93ee3c5e133697251b5362bcf9cc8532476785t8768075616f58d88</td><td>Your Tylt API Key, used to identify your account in API requests.</td></tr><tr><td>X-TLP-SIGNATURE</td><td>string</td><td>d0afef3853dfc8489c8b9affa5825171fdd7y7685675e4966a05f66ed2b3eaf9462b3c9c0</td><td>HMAC SHA-256 signature generated using the API Secret Key to secure the request.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

{% hint style="info" %}
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.
{% endhint %}

**Request Body**

{% tabs %}
{% tab title="Body" %}

<table data-header-hidden><thead><tr><th width="204"></th><th width="121"></th><th></th></tr></thead><tbody><tr><td><strong>Field Name</strong></td><td><strong>Type</strong></td><td><strong>Description</strong></td></tr><tr><td><code>merchantOrderId</code></td><td><code>string</code></td><td>The order ID provided by the Merchant for local reference.</td></tr><tr><td><code>baseAmount</code></td><td><code>number</code></td><td>The amount to be paid.</td></tr><tr><td><code>baseCurrency</code></td><td><code>string</code></td><td>The base currency of the good/service being supplied.</td></tr><tr><td><code>settledCurrency</code></td><td><code>string</code></td><td>The currency in which the payment is to be made.</td></tr><tr><td><code>networkSymbol</code></td><td><code>string</code></td><td>The network symbol for the transaction (e.g., BSC).</td></tr><tr><td><code>callBackUrl</code></td><td><code>string</code></td><td>URL for the callback after transaction completion.</td></tr><tr><td><code>customerName</code></td><td><code>string</code></td><td>Optional: Customer's name for the transaction.</td></tr><tr><td><code>comments</code></td><td><code>string</code></td><td>Optional: Comments for additional context.</td></tr><tr><td><code>settleUnderpayment</code></td><td><code>number</code></td><td><p>This parameter determines how the system handles <strong>underpayments</strong> — cases where the customer pays <strong>less than the expected amount</strong>.</p><hr><p><strong>If <code>settleUnderpayment = 1</code> (Default):</strong></p><ul><li>The transaction will be <strong>automatically settled</strong>, even if the customer sends <strong>less than the required amount</strong>.</li><li>No further payment is expected.</li><li>The merchant assumes responsibility for accepting the shortfall. Refer settledAmountReceived and baseAmountRecieved via the webhook to handle business logic.</li></ul><hr><p><strong>If <code>settleUnderpayment = 0</code>:</strong></p><ul><li>The transaction will <strong>remain unsettled</strong> until the <strong>full expected amount</strong> is received.</li><li>The customer must complete the remaining payment <strong>before the payment intent expires</strong>.</li><li>If the full amount is <strong>not received by the expiry time</strong>, the payment intent will <strong>expire</strong>, and the transaction will Be <strong>settled as underpayment.</strong><br><br>Refer settledAmountReceived and baseAmountRecieved via the webhook to handle business logic.</li></ul></td></tr><tr><td><code>payeeDetails</code></td><td><code>json Object</code></td><td><p>Mandatory object containing Travel Rule data for the transaction originator, required for AML/CFT compliance. <br><br>Structure varies by <code>entityType</code>.</p><p><strong>entityType</strong><br>Specifies originator type: <code>individual</code> or <code>company</code>.<br></p><p><strong>individual</strong><br>Required if <code>entityType = individual</code>. <br>===========================<br><code>firstName</code>, <br><code>lastName</code>, <br><code>DOB</code> (YYYY-MM-DD), <br><code>placeOfBirth</code><br></p><p><strong>company</strong><br>Required if <code>entityType = company</code>.<br>===========================  <br><code>fullName</code>,<br>"<code>address</code>": {<br>"<code>country</code>": "DEU",<br>"<code>town</code>": "Berlin",<br>"<code>postCode</code>": "10115",<br>"<code>street</code>": "Chauseestr.",<br>"<code>buildingNumber</code>": "60"<br>}</p></td></tr></tbody></table>

{% endtab %}
{% endtabs %}

**Code Snippet**

{% tabs %}
{% tab title="JavaScript (Axios)" %}

```javascript
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'
    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));

```

{% endtab %}

{% tab title="Python" %}

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

```

{% endtab %}

{% tab title="JavaScript (Fetch)" %}

```javascript
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));

```

{% endtab %}
{% endtabs %}

**Response**

{% tabs %}
{% tab title="200" %}

<pre class="language-json"><code class="lang-json">{
    "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":<a data-footnote-ref href="#user-content-fn-1"> </a>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": ""
}
</code></pre>

{% endtab %}

{% tab title="Response Fields" %}

<table data-header-hidden><thead><tr><th width="236"></th><th width="96"></th><th></th></tr></thead><tbody><tr><td><strong>Field Name</strong></td><td><strong>Type</strong></td><td><strong>Description</strong></td></tr><tr><td>orderId</td><td>string</td><td>The order ID generated by TL Pay.</td></tr><tr><td>merchantOrderId</td><td>string</td><td>The order ID provided by the Merchant at the time of request.</td></tr><tr><td>baseAmount</td><td>number</td><td>The  value of the good/service being supplied expressed in the baseCurrency</td></tr><tr><td>baseCurrency</td><td>string</td><td>The base currency of the good/service. (symbol)</td></tr><tr><td>settledCurrency</td><td>string</td><td>The crypto currency in which the payment is to be made by the customer. (symbol)</td></tr><tr><td>settledAmountRequested</td><td>number</td><td>The amount of crypto currency requested from the customer.</td></tr><tr><td>settledAmountReceived</td><td>number</td><td>The amount of  crypto currency received from the customer.</td></tr><tr><td>settledAmountCredited</td><td>number</td><td>The amount of crypto currency credited to your balance.</td></tr><tr><td>commission</td><td>number</td><td>The commission deducted for the transaction.</td></tr><tr><td>network</td><td>string</td><td>The crypto network used for the payment.</td></tr><tr><td>depositAddress</td><td>string</td><td>The address where the payment should be sent by the customer.</td></tr><tr><td>status</td><td>string</td><td>The status of the transaction (e.g., Pending, Completed).</td></tr><tr><td>paymentURL</td><td>string</td><td>The URL for the customer to make the payment.</td></tr><tr><td>callBackURL</td><td>string</td><td>The URL for callback notifications.</td></tr><tr><td>transactions</td><td>array</td><td>Details of the transactions associated with the payment.</td></tr><tr><td>createdAt</td><td>string</td><td>The timestamp when the request was created.</td></tr><tr><td>expiresAt</td><td>string</td><td>The timestamp when the request expires.</td></tr><tr><td>updatedAt</td><td>string</td><td>The timestamp when the request was last updated.</td></tr><tr><td>isFinal</td><td>number</td><td>Indicates if the transaction is completed (1) or pending (0).</td></tr><tr><td>isCredited</td><td>number</td><td>Indicates if the payment has been credited (1) or not (0).</td></tr><tr><td>customerName</td><td>string</td><td>The name of the customer making the payment.</td></tr><tr><td>comments</td><td>string</td><td>Additional comments provided during the request.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

***

#### <mark style="background-color:orange;">**Understanding BaseCurrency and SettledCurrency in Pay-In Requests**</mark>

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.

{% hint style="info" %}
**Important Notes:**

The **baseCurrency** can be either a supported fiat or cryptocurrency. The **settledCurrency** will always be a cryptocurrency.
{% endhint %}

[^1]:


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tylt.money/tylt-cpg-crypto-asset-gateway/api-reference/accept-crypto-assets/creating-a-pay-in-request.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.