# Create a Pay-Out Instance

This endpoint creates a new Open Banking **off-ramp instance** and returns a widget launch URL. The merchant can use this URL to launch the Tylt CrossRamp Open Banking off-ramp widget, where the end user completes the off-ramp flow and receives fiat via Open Banking.

**Flow outcome:**

* The merchant initiates a transfer of USDC to the end user
* The end user completes the off-ramp flow via the hosted widget
* The corresponding fiat amount is made available to the end user via SEPA instant
* The merchant’s USDC balance is debited for the corresponding amount (including applicable fees, if any)

**Endpoint**

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

**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>payeeDetails</code></td><td><code>JSON Object</code></td><td><p>Bank Account Details (Payout Destination)</p><p>Use this object to capture the user’s payout destination bank account—i.e., the bank account where fiat funds will be paid out.</p><p></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>iban</code> (string)</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 withdraw in EUR.</td></tr><tr><td><code>currencySymbol</code></td><td><code>string</code></td><td>Mandatory. Supported Currency is "EUR" 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><tr><td><code>autoMerchantApproval</code></td><td><code>bool</code></td><td><strong>Default: <code>1</code></strong><br><code>1</code> =  Auto-approved; payout processed automatically after customer submission and KYC where applicable<br><code>0</code> = payout queued for merchant approval after customer submission and KYC where applicable. Requires merchant approval via approvePayout to move to processing.</td></tr><tr><td></td><td></td><td></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: 'EUR',
    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",
            autoMerchantApproval : 0
<strong>    },
</strong><strong>   payeeDetails: {
</strong>            iban: "FR7630006000011234567890185"
    }
<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/instance/payout', 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-eur-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" 
    },
    "payeeDetails": {
      "iban": "FR7630006000011234567890185"
    },
    "merchantDetils":{ 
      "merchantName": "Example Merchant Ltd",
      "merchantUrl": "https://www.examplemerchant.com",
      "merchantInternalId": "merchant-12345"
    },
    "fiatAmount": 4000,
    "fiatCurrencySymbol": "EUR",
    "cryptoAmount": 4686.58,
    "cryptoCurrencySymbol": "USDC",
    "rate": 0.8535
  }
}
```

{% 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 EUR Open Banking 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.         |
| `payeeDetails`         | Object | Object containing users bank account details where the payment will be made.                   |
| `fiatAmount`           | Number | Amount to be paid by the customer.                                                             |
| `fiatCurrencySymbol`   | String | Fiat currency used in the transaction — always `EUR`.                                          |
| `cryptoAmount`         | Number | Amount of USDC to be debited from the merchant upon successful initiation of the payout.       |
| `cryptoCurrencySymbol` | String | Crypto currency used for settlement — always `USDC`.                                           |
| `rate`                 | Number | EUR → USDC 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/eu-open-banking/open-banking-payout-usdc-eur/create-a-pay-out-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.