BTM File - Usage & Requirements

Overview

The BTM file upload endpoint expects the payment file as a raw stream in the HTTP request body. Multipart uploads are not supported. For the mapping engine channel (_btm.mappingEngine), you must also provide a file-format indicating the actual payment schema (PAIN_001_001_03) rather than a MIME type.

Endpoint

POST https://api-mtls.eu.tispayments.com/rest/api/btm/files

Transport / Security

TLS: Mutual TLS (mTLS) with a client certificate is required.

More details can be found on https://api-docs.tispayments.com/docs/getting-started#mutual-tls

Host: api-mtls.eu.tispayments.com

Configure your client certificate in your HTTP client/tooling (Postman Certificates or cURL --cert/--key).

Required Headers

Important: Some clients (Postman) can auto-set Content-Type. Ensure you have exactly one Content-Type header. Duplicate entries can cause empty or malformed payloads.

Query Parameters

Place the following parameters on the query string

For _btm.mappingEngine, file-format must correspond to the specific payment scheme/version contained in the file (PAIN_001_001_03, PAIN_001_001_06, etc.).

Request Body Format

• Body: the raw file contents as the request body (binary stream).
• Do not wrap the file in multipart form-data (no boundaries, no part headers).

Examples

✅ Python (correct: raw/binary upload)

import requests

url = "https://api-mtls.eu.tispayments.com/rest/api/btm/files"
headers = {
    "accept": "application/json",
    "content-type": "text/xml",
    "TIS-API-MODE": "BTM"
}
params = {
    "file-name": "your_file.xml",
    "client-system-id": "your-system-id",
    "channel": "_btm.mappingEngine",
    "file-format": "PAIN_001_001_03"
}

with open("your_file.xml", "rb") as f:
    resp = requests.post(url, headers=headers, params=params, data=f)

print(resp.status_code)
print(resp.text)

✅ cURL — correct binary upload

curl -X POST "https://api-mtls.eu.tispayments.com/rest/api/btm/files?file-name=your_file.xml&client-system-id=your-system-id&channel=_btm.mappingEngine&file-format=PAIN_001_001_03" \
  -H "Accept: application/json" \
  -H "Content-Type: text/xml" \
  -H "TIS-API-MODE: BTM" \
  --data-binary "@your_file.xml" \
  --cert /path/to/client.crt --key /path/to/client.key

❌ Python — incorrect multipart (unsupported)

# WRONG: using `files=` sends multipart/form-data

import requests

url = "https://api-mtls.eu.tispayments.com/rest/api/btm/files"
headers = {"accept": "application/json"}

params = {
    "file-name": "your_file.xml",
    "client-system-id": "your-system-id",
    "channel": "_btm.mappingEngine",
    "file-format": "PAIN_001_001_03"
}

with open("your_file.xml", "rb") as file:
    files = {"file": ("your_file.xml", file, "text/xml")}
    response = requests.post(url, headers=headers, params=params, files=files)  # WRONG

Postman Instructions

1. Method: POST
2. URL: https://api-mtls.eu.tispayments.com/rest/api/btm/files
3. Params tab: add file-name, client-system-id, channel, and (if using _btm.mappingEngine) file-format.
4. Headers tab:Accept: application/json
   • Content-Type: text/xml (exactly one!)
   • TIS-API-MODE: BTM 1.Body tab: select binary, then choose your file. Do not use form-data.
5. Certificates (mTLS): configure your client certificate in Postman Settings → Certificates and map it to api-mtls.eu.tispayments.com.
6. Send the request.

Common pitfall: Having two Content-Type headers stops Postman from applying the correct content-type for binary bodies and may result in empty files server-side.

FAQ

Q: Why can’t I use multipart/form-data? A: The endpoint reads the request body as a raw stream. Multipart adds boundaries and part headers that are not parsed by this service.

Q: Which Content-Type should I use? A: Use text/xml for XML payment files. application/octet-stream is acceptable for generic binary payloads. Do not set multiple Content-Type headers.

Q: What should I put in file-format? A: The payment format identifier (PAIN_001_001_03), not a MIME type. It must match the actual file content for correct in-mapping.