# 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 qrPH Pay-In widget. Through the widget, the merchant's end customer can make a deposit or payment to the merchant using qrPH in PHP. The payment is settled in USDT into the merchants wallet.

**Endpoint**

<mark style="color:green;">**`POST`**</mark>`https://api.tylt.money/v2/prime-fiat/php/instance/payin`

**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>userDetails</code></td><td><code>JSON Object</code></td><td><p>Custom fields associated with the end user making a payment to the merchant. These fields are echoed back in webhook notifications and other API responses for tracking and reconciliation.You may send an empty object (<code>{}</code>).<br></p><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:</p><ul><li><code>firstName</code> (string)</li><li><code>lastName</code> (string)</li><li><code>email</code> (string)</li><li><code>country</code> (string)</li><li><code>dob</code> (string, format: <code>YYYY-MM-DD</code>)<br></li></ul><p>If a reserved field is not provided, the end user will be prompted to enter that field in the widget (if required by the flow).</p></td></tr><tr><td><code>merchantOrderId</code></td><td><code>string</code></td><td>Mandatory. 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>Mandatory. The URL to which payment status updates are sent.</td></tr><tr><td><code>redirectUrl</code></td><td><code>string</code></td><td>Mandatory. 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 PHP.</td></tr><tr><td><code>currencySymbol</code></td><td><code>string</code></td><td>Mandatory. Supported Currency is "PHP" only</td></tr><tr><td><code>merchantDetails</code></td><td><code>JSON Object</code></td><td><p>The <code>merchantDetails</code> object identifies the merchant on whose behalf the transaction is being processed. This information is required for transaction attribution, reconciliation, risk screening, and regulatory reporting.<br><br>If the integrator is acting as a Merchant of Record, the details of the underlying end merchant must be provided<br><br>If the integrator is the end merchant, the details of its own business must be provided. <br><br>The following fields must be provided inside the <code>merchantDetails</code> object:</p><ul><li><strong>merchantName</strong><br>The legal or DBA name of the merchant.</li><li><strong>merchantUrl</strong><br>The official website URL of the merchant. This must be a valid HTTPS URL representing the merchant’s active operating website.</li><li><strong>merchantInternalId</strong><br>A unique internal identifier assigned by the merchant. This identifier is used for reconciliation, reporting, and ongoing transaction tracking and must remain consistent across transactions.</li></ul><p>All fields within <code>merchantDetails</code> are mandatory. Transactions submitted without this object, or with incomplete merchant details, will be rejected.<br><br>Transactions with new <code>merchantDetails</code> go through an automated internal review process. </p></td></tr><tr><td><code>cryptoUi</code></td><td><code>number</code></td><td>Controls the visual mode of the hosted payment widget. Default is <code>1</code>. If set to <code>1</code>, the widget UI is adapted to showcase a crypto purchase flow. If set to <code>0</code>, the widget UI is adapted to showcase a fiat payment flow.</td></tr></tbody></table>

{% endtab %}
{% endtabs %}

**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 = {
    merchantOrderId: 'b73b73b-87wtbc-q36gbc-331n3', // please use a unique order id per request
    callBackUrl: 'https://www.test.com/callback',
    redirectUrl: 'https://www.test.com/callback',
    amount: 10.00,
    currencySymbol: 'PHP',
    merchantDetails: {
        merchantName: "Example Merchant Ltd",
        merchantUrl: "https://www.examplemerchant.com",
        merchantInternalId: "merchant-12345" 
    },
    userDetails: {
            firstName: "Test",
            lastName: "User",
            email: `testuser@testemail.com`,
            country: "Poland",
            dob: "1990-01-01",
            DocumentType: "Identity Card",
            DocumentNumber: "426349253ZY8",
            DocumentURL : "https://kyc.gaming.com/b1278191.jpeg"          
<strong>    }
</strong><strong>};
</strong>
// 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/v2/prime-fiat/php/instance/payin', raw, { headers })
    .then(response => console.log("Success:", response.data))
    .catch(error => console.error("Error:", error));

</code></pre>

{% endtab %}
{% endtabs %}

**Response**

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

```json
{
  "msg": "Ivy instance created successfully",
  "data": {
    "instanceId": "467153bc-72a8-466d-8fb1-59b080250554",
    "merchantOrderId": "merchant-test-gWsQ1fiLmk",
    "url": "https://app.tylt.money/prime-php-instance/467153bc-72a8-466d-8fb1-59b080250554",
    "userDetails": {
      "firstName": "Test",
      "lastName": "User",
      "email": "testuser@testemail.com",
      "country": "Poland",
      "dob": "1990-01-01",
      "DocumentType": "Identity Card",
      "DocumentNumber": "426349253ZY8",
      "DocumentURL": "https://kyc.gaming.com/b1278191.jpeg" 
    },
    "merchantDetils":{ 
            "merchantName": "Example Merchant Ltd",
            "merchantUrl": "https://www.examplemerchant.com",
            "merchantInternalId": "merchant-12345"
    },
    "fiatAmount": 4000,
    "fiatCurrencySymbol": "PHP",
    "cryptoAmount": 69.00,
    "cryptoCurrencySymbol": "USDT",
    "rate": 57.97
  }
}
```

{% endtab %}

{% tab title="Response Fields" %}

| Field                  | Type   | Description                                                                              |
| ---------------------- | ------ | ---------------------------------------------------------------------------------------- |
| `instanceId`           | String | Unique identifier for the  Open Banking payment instance.                                |
| `merchantOrderId`      | String | Merchant-provided order reference used for internal tracking and reconciliation.         |
| `url`                  | String | Hosted checkout URL where the customer is redirected to complete the PHP qrPH payment.   |
| `userDetails`          | Object | Merchant-supplied customer metadata returned exactly as provided in the request.         |
| `merchantDetails`      | Object | Object containing merchant identification information associated with the transaction.   |
| `fiatAmount`           | Number | Amount to be paid by the customer.                                                       |
| `fiatCurrencySymbol`   | String | Fiat currency used in the transaction — always `PHP`.                                    |
| `cryptoAmount`         | Number | Amount of USDT to be credited to the merchant upon successful completion of the payment. |
| `cryptoCurrencySymbol` | String | Crypto currency used for settlement — always `USDT`.                                     |
| `rate`                 | Number | PHP → USDT conversion rate applied at the time the quote was generated.                  |
| {% 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/philippines-php/qrph-payin-php-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.