# 3. File 📁

## **Initiate Payment (File)**

<mark style="color:green;">`POST`</mark> `{{Base Adres}}/api/paywall/payment/bulk/file/startdirect`

{% hint style="info" %}
**Important:** To use the bulk payment initiation service, you must include the **apikeypublic** and **apiclientpublic** parameters in the header.\
[<mark style="color:green;">**PaymentAPI Address**</mark>](/payment-orchestration-integration-document/environment.md)
{% endhint %}

{% hint style="info" %}
You can send a maximum of 150,000 transactions to the bulk payment service within the file model. After submitting the bulk payment request, only the **BulkPaymentId** is returned in the API response. All transactions are then processed by the Paywall queue mechanism.
{% endhint %}

{% hint style="warning" %}
The File 📁 model is designed to handle high-volume data processing. Therefore, we strongly recommend using **GZip** or **Brotli** compression for your requests. This ensures that the data transmitted over the network is compressed, reducing latency by up to **90%**.
{% endhint %}

{% hint style="warning" %}
In the File 📁 model, bulk payment requests submitted between **23:00 and 00:00** are processed after midnight, starting from **02:00**. This waiting period is applied to ensure the consistency of financial reports.\
\
[<mark style="color:blue;">**\</> Example Code**</mark>](broken://pages/YVNr8gFnFs3vrepqgHJP)
{% endhint %}

{% hint style="warning" %}
In the File 📁 model, data is received via **Form-Data**.
{% endhint %}

<table><thead><tr><th width="188">Parameter</th><th width="93.64453125">Type</th><th width="137.44921875">Compolsory</th><th width="403">Description</th></tr></thead><tbody><tr><td>apikeypublic</td><td>string</td><td>Yes</td><td>The <strong>Public Key</strong> you obtained from the merchant panel.</td></tr><tr><td>apiclientpublic</td><td>string</td><td>Yes</td><td>The <strong>Public Client</strong> you obtained from the merchant panel.</td></tr></tbody></table>

Sample <mark style="color:$success;">**Form-Data**</mark> parameters to be sent to the service are as follows.

<table><thead><tr><th width="189.94140625">Parameter</th><th width="122.83203125">Type</th><th width="156.38720703125">Compuılsory</th><th width="336">Description</th></tr></thead><tbody><tr><td>FileFormat</td><td>short</td><td>Yes</td><td>File type of the file containing the payment details.i<br><br>See: <a href="/pages/tZak9gsGiH3lwLBvFj6t">File Patterns</a></td></tr><tr><td>File</td><td>File</td><td>Yes</td><td>File containing the payment details</td></tr><tr><td>FilePattern</td><td>short</td><td>Yes</td><td>This parameter defines the pattern of the file containing the payment details. It enables Paywall to recognize and process the file content correctly.<br><br>See: <a href="/pages/tZak9gsGiH3lwLBvFj6t">File Patterns</a></td></tr><tr><td>CurrencyId</td><td>int</td><td>Yes</td><td><p><strong>Currency</strong></p><p></p><p><strong>Note:</strong> If provided, all payments will be processed using the specified currency value. If not provided, <strong>TRY</strong> will be used as the default.</p></td></tr><tr><td>Installment</td><td>int</td><td>No</td><td><p><strong>Installment</strong></p><p></p><p><strong>Note:</strong> If provided, all payments will be processed using the specified installment value. If not provided, transactions will be processed as <strong>single (non-installment)</strong> by default.</p></td></tr><tr><td>CallbackAddress</td><td>string</td><td>No</td><td><p><strong>Callback Address</strong></p><p></p><p><strong>Note:</strong> If the <strong>CallbackAddress</strong> is provided, the responses for bulk payments initiated via file will also be sent as a file. Therefore, the specified endpoint must be designed to receive the response file via <strong>form-data</strong> with the parameter name <strong>File</strong>.</p><p><br>See: <a href="/pages/td4tSOlY4HS4cHQAxjZH">Submitted File</a></p></td></tr><tr><td>Half2D</td><td>bool</td><td>No</td><td>Indicates whether the payment will be authorized (pre-authorized) or not.</td></tr><tr><td>Amount</td><td>decimal</td><td>No</td><td>If not specified, it will be calculated based on the data within the file.</td></tr><tr><td>MerchantUniqueCode</td><td>string</td><td>No</td><td><p><strong>Primary tracking code for the bulk payment.</strong></p><p></p><p><strong>Note:</strong> If not provided in the request, it will be generated automatically.</p></td></tr><tr><td>TrackingCode</td><td>string</td><td>No</td><td><p><strong>Secondary tracking code for the bulk payment.</strong></p><p></p><p><strong>Note:</strong> If not provided in the request, it will be generated automatically.</p></td></tr><tr><td>CallbackBodyCompression</td><td>bool</td><td>No</td><td>If the relevant parameter is sent as <strong><code>true</code></strong>, the response will be compressed and sent to the address specified in the <strong><code>CallbackAddress</code></strong> parameter.</td></tr></tbody></table>

**Response returned from the service:**

<table><thead><tr><th width="189">Parameter</th><th width="100.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>ErrorCode</td><td>int</td><td><strong>Error code.</strong> Returns <code>'0'</code> if the operation is successful.</td></tr><tr><td>Result</td><td>bool</td><td>Returns <strong>true</strong> if the operation is successful, <strong>false</strong> if it fails.</td></tr><tr><td>Message</td><td>string</td><td>Contains information about the operation or an error message.</td></tr><tr><td>Body</td><td>object</td><td>Detailed information about the bulk payment transaction.</td></tr></tbody></table>

**Example Code**

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

```json
{
    "ErrorCodeType": 1,
    "ErrorMessage": null,
    "ErrorCode": 0,
    "Result": true,
    "Message": "File-based bulk payment created and enqueued",
    "Body": {
        "BulkPaymentId": 3467,
        "MerchantUniqueCode": "bc110eb7-1c52-40e2-ae91-705d00cdbe8a",
        "ProcessedRecords": 0,
        "TotalRecords": 10,
        "IsEnqueued": true,
        "Message": "File-based bulk payment created and enqueued for processing"
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Responses for bulk payments processed via file are also delivered as a file. You can always access the response file from the Paywall panel. Additionally, if you provide a **CallbackAddress** during the bulk payment initiation, the file will also be sent to the specified address.

**See:** [Bulk Payment Result File](broken://pages/5hhcXDIleP7YqEB8xFt8)
{% endhint %}


---

# 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://developer.paywall.one/payment-orchestration-integration-document/payment-service/18.-batch-processing-method/1.-payment/3.-file.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.