# Create a Pay-in Instance

This endpoint allows you to create a new payment instance and receive a URL that can be used to launch the **Tylt CrossRamp Pay-In widget.** Through the widget, the merchant's end customer can make a deposit or payment to the merchant using **PIX**. The payment is settled in USDT into the merchants wallet.

**Endpoint**

<mark style="color:green;">**`POST`**</mark>`https://api.tylt.money/v2/prime/BR/PIX/instance`

**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="warning" %}
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>isBuyTrade</code></td><td><code>number</code></td><td>Must be set to 1 for a Pay-In transaction.</td></tr><tr><td><code>userDetails</code></td><td><code>JSON Object</code></td><td><p>Free-form object containing merchant-defined user metadata. This object may include any fields for tracking and reconciliation and is returned in webhooks and API responses.</p><p><br><strong>Reserved Keys  (for Auto-KYC)</strong></p><p>Certain keys (e.g., <code>kyc</code>) are reserved for system-level processing. If provided, they must follow the defined schema and will be used for workflows such as reusable KYC (e.g., Didit session reuse).<br></p><p>The reserved key <code>kyc</code> (object) enables reusable KYC with the following structure:<br><code>{ source: "Didit", sessionId: string }</code></p><p>Provide the <code>sessionId</code> of a completed Didit verification. The system will attempt to import and validate the session; if successful, the user may skip KYC, otherwise the standard KYC flow applies.<br></p><p>For more details on setting up Didit reusable KYC, refer to the official documentation.</p></td></tr><tr><td><code>pixDetails</code></td><td><code>JSON Object</code></td><td><p><strong>Reserved keys  (auto-populate payment widget)</strong><br></p><p>The following keys are reserved. If you include any of them, they will be used to pre-fill the corresponding fields in the hosted payment widget:<br></p><ul><li><code>fullName</code> (string)</li><li><code>cpfKey</code> (string)</li></ul><p></p><p>If a reserved field is not provided, the end user will be prompted to enter that field in the widget.</p></td></tr><tr><td><code>merchantOrderId</code></td><td><code>string</code></td><td>A UUID used by the merchant to reference this instance or any transaction related to it.</td></tr><tr><td><code>callBackUrl</code></td><td><code>string</code></td><td>The URL to which payment status updates are sent.</td></tr><tr><td><code>redirectUrl</code></td><td><code>string</code></td><td>The URL to redirect the user after completing the payment.</td></tr><tr><td><code>amount</code></td><td><code>number</code></td><td>Mandatory. This is the amount the user wants to deposit in USDT or BRL equivalent.</td></tr><tr><td><code>currencySymbol</code></td><td><code>string</code></td><td>Supported Currency is "USDT" or "BRL" only.</td></tr><tr><td><code>network</code></td><td><code>string</code></td><td><strong>Only for Instant Channel:</strong> The <strong>network</strong> of the self-hosted wallet where the crypto will be settled. Accepted values: <code>"ETH"</code>, <code>"TRX"</code>, <code>"AVAX"</code>, <code>"TON"</code>, <code>"SOL"</code></td></tr><tr><td><code>walletAddress</code></td><td><code>string</code></td><td><strong>Only for Instant Channel:</strong> Please provide the public address of your self-hosted wallet where the crypto will be settled.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
**API Keys and Wallet / Network Configuration — Instant Channel Settlement:**\
Please use the API Key associated with the designated wallet — PIX Instant Payin.

Before initiating settlements, kindly share the network and wallet address details in advance with the technical service team for whitelisting and template creation. This process typically takes 4–6 hours to complete.\
\
**Network Fees & MDR — Instant Channel Settlement**\
On Instant Settlement transactions, both MDR fees and network fees are automatically deducted from your PIX Instant Payin (Cross-Ramp) wallet balance, while the payment amount is transferred on-chain.

***

**Example**

If a payment of **165 BRL (≈ 30 USDT)** is initiated:

* On successful payment, 30 USDT is sent on-chain to the recipient.
* The network fee (e.g., 1 USDT) and the MDR fee (e.g., 0.45 USDT) are debited from your wallet balance.
* In this case, your wallet must hold enough balance to cover both the 1 USDT network fee and 0.45 USDT MDR fee at the time of creation.

***

**Wallet Balance Requirement**

A minimum balance of 50 USDT must be maintained in your PIX Instant Payin (Cross-Ramp) wallet to create a new payment link or transaction. Please ensure that the wallet remains sufficiently funded to cover on-chain gas costs and MDR fees, as these are deducted directly from your wallet balance for each transaction.
{% endhint %}

**Code Snippet**

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

<pre class="language-javascript"><code class="lang-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 = {
    isBuyTrade: 1,
    userDetails: {},
    pixDetails: {
            fullName: "Joao Pedro Barbosa",
            cpfKey: "03475666006"
        },
    merchantOrderId: crypto.randomUUID(),
    callBackUrl: "https://www.test.com/callback",
    redirectUrl: "https://www.test.com/callback",
    amount: 10.00,
    currencySymbol: "BRL",
// Required only for PIX Instant Payin Channel:
    walletAddress: "0xd2AF4B117EfE474B66Fc79E6A8E1938D41a60F4c", // Public address of self-hosted wallet for crypto settlement
    network:"ETH" // Network of the self-hosted wallet — accepted values: "ETH", "TRX", "AVAX", "TON", "SOL"
<strong>};
</strong>
// Print request body for reference
console.log("requestBody", requestBody);

// 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/v2/prime/BR/PIX/instance', raw, { headers })
    .then(response => console.log("Success:", response.data))
    .catch(error => console.error("Error:", error));

</code></pre>

{% endtab %}

{% tab title="Python" %}

```python
import json
import hashlib
import hmac
import requests
import uuid

# Replace with your API Key and Secret
api_key = 'your-api-key'
api_secret = 'your-api-secret'

# Function to create HMAC SHA-256 signature
def create_signature(secret, data):
    return hmac.new(secret.encode(), data.encode(), hashlib.sha256).hexdigest()

# Function to send a POST request
def send_post_request(url, body):
    raw = json.dumps(body, separators=(',', ':'), ensure_ascii=False)
    signature = create_signature(api_secret, raw)

    headers = {
        'Content-Type': 'application/json',
        'X-TLP-APIKEY': api_key,
        'X-TLP-SIGNATURE': signature
    }

    response = requests.post(url, headers=headers, data=raw)
    return response.json()

# Request body
request_body = {
    "isBuyTrade": 1,
    "userDetails": {},
    "pixDetails": {
            "fullName": "Joao Pedro Barbosa",
            "cpfKey": "03475666006"
        },
    "merchantOrderId": str(uuid.uuid4()),
    "callBackUrl": 'https://www.test.com/callback',
    "redirectUrl": 'https://www.test.com/callback',
    "amount": 10,
    "currencySymbol" : 'BRL',
     # Required only for PIX Instant Payin Channel:
    "walletAddress": '0xd2AF4B117EfE474B66Fc79E6A8E1938D41a60F4c', # Public address of self-hosted wallet for crypto settlement
    "network":'ETH' # Network of the self-hosted wallet — accepted values: "ETH", "TRX", "AVAX", "TON", "SOL"
}

# Print request body for reference
print('request_body',request_body)

# Send the request
response = send_post_request('https://api.tylt.money/v2/prime/BR/PIX/instance', request_body)
print("Response:", response)


```

{% 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 = {
    isBuyTrade: 1,
    userDetails: {},
    pixDetails: {
            fullName: "Joao Pedro Barbosa",
            cpfKey: "03475666006"
        },
    merchantOrderId: crypto.randomUUID(),
    callBackUrl: 'https://www.test.com/callback',
    redirectUrl: 'https://www.test.com/callback',
    amount: 10.00,
    currencySymbol: 'BRL',
    
// Required only for Instant (INSTI) Channel:
    walletAddress: "0xd2AF4B117EfE474B66Fc79E6A8E1938D41a60F4c", // Public address of self-hosted wallet for crypto settlement
    network:"ETH" // Network of the self-hosted wallet — accepted values: "ETH", "TRX", "AVAX", "TON", "SOL"
};

//Print request body for reference
console.log("requestBody", requestBody)

// 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/v2/prime/BR/PIX/instance', headers, raw)
    .then(result => console.log("Success:", result))
    .catch(error => console.error("Error:", error));
re
```

{% endtab %}
{% endtabs %}

**Response**

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

```json
{
    "msg": "Instance created successfully",
    "data": {
        "url": "https://app.tylt.money/prime-brl/d0f6cc25-e8f8-11ef-830e-02d8461243e9",
        "instanceId": "d0f6cc25-e8f8-11ef-830e-02d8461243e9",
        "tradeId": 10432

        }    
}
```

{% 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>url</td><td>string</td><td>The unique link to the Tylt Prime Payment widget. You can display this url either on iframe or a browser.</td></tr><tr><td>instanceId</td><td>string</td><td>The instance ID generated by Tylt, used as a UUID global identifier. </td></tr><tr><td>tradeId</td><td>number</td><td>The trade ID generated by Tylt, used as a numerical unique global identifier</td></tr></tbody></table>
{% endtab %}
{% endtabs %}


---

# 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/introduction/tylt-crossramp-fiat-crypto-solutions/brazil-brl/pix-payin-brl-usdt/create-a-pay-in-instance.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.