Document Payments

Create document payment

Creates a new payment for a public document.

Supported document types

Only invoice, proforma, and credit-note are supported.

Business behavior

The payment is always linked to one document via documentType + documentId.
The minimal create payload is only documentType + documentId; all other fields can be omitted and are derived server-side.
If paymentDate is omitted, today’s date is used.
If paymentMethodId is omitted, the payment method from the source document is used.
If currencyId is omitted, the currency from the source document is used.
If amount is omitted, the current remaining toBePaid amount from the source document is used. This shortcut only works when the document still has a non-zero toBePaid; otherwise the endpoint returns 422.
If amount is sent explicitly, it can have at most 2 decimal places.
If amount is sent explicitly, its magnitude must not exceed the current toBePaid and it must keep the same sign, so the payment cannot over-settle the document or move in the opposite direction.
If currencyRate is omitted, the system derives it from the final paymentDate using the previous day’s rate.
If you send currencyRate for a currency other than EUR, that override value is used as-is.
If the final payment currency is EUR, the backend always stores and returns currencyRate = 1.0, even when you send a different value.
Creating a payment recalculates the document payment status exactly like the web and mobile flows.
If you later issue a payment receipt invoice for a proforma payment, the payment response may expose it in receiptInvoice.

If you send an Idempotency-Key, the same key with the same payload returns the original response without creating the payment again.

POST

document-payments

Create document payment

curl --request POST \
  --url https://app.fintoro.sk/api/public/v1/document-payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "documentType": "invoice",
  "documentId": 301,
  "currencyId": 1,
  "currencyRate": 1,
  "paymentDate": "2026-03-07",
  "paymentMethodId": 1,
  "amount": 15.5
}
'

import requests

url = "https://app.fintoro.sk/api/public/v1/document-payments"

payload = {
    "documentType": "invoice",
    "documentId": 301,
    "currencyId": 1,
    "currencyRate": 1,
    "paymentDate": "2026-03-07",
    "paymentMethodId": 1,
    "amount": 15.5
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    documentType: 'invoice',
    documentId: 301,
    currencyId: 1,
    currencyRate: 1,
    paymentDate: '2026-03-07',
    paymentMethodId: 1,
    amount: 15.5
  })
};

fetch('https://app.fintoro.sk/api/public/v1/document-payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.fintoro.sk/api/public/v1/document-payments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'documentType' => 'invoice',
    'documentId' => 301,
    'currencyId' => 1,
    'currencyRate' => 1,
    'paymentDate' => '2026-03-07',
    'paymentMethodId' => 1,
    'amount' => 15.5
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.fintoro.sk/api/public/v1/document-payments"

	payload := strings.NewReader("{\n  \"documentType\": \"invoice\",\n  \"documentId\": 301,\n  \"currencyId\": 1,\n  \"currencyRate\": 1,\n  \"paymentDate\": \"2026-03-07\",\n  \"paymentMethodId\": 1,\n  \"amount\": 15.5\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.fintoro.sk/api/public/v1/document-payments")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"documentType\": \"invoice\",\n  \"documentId\": 301,\n  \"currencyId\": 1,\n  \"currencyRate\": 1,\n  \"paymentDate\": \"2026-03-07\",\n  \"paymentMethodId\": 1,\n  \"amount\": 15.5\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.fintoro.sk/api/public/v1/document-payments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"documentType\": \"invoice\",\n  \"documentId\": 301,\n  \"currencyId\": 1,\n  \"currencyRate\": 1,\n  \"paymentDate\": \"2026-03-07\",\n  \"paymentMethodId\": 1,\n  \"amount\": 15.5\n}"

response = http.request(request)
puts response.read_body

{
  "id": 801,
  "documentType": "invoice",
  "documentId": 301,
  "paymentMethod": {
    "id": 1,
    "name": "Bank transfer"
  },
  "currency": {
    "id": 1,
    "symbol": "EUR",
    "name": "Euro",
    "mark": "€"
  },
  "paymentDate": "2026-03-07",
  "amount": 15.5,
  "currencyRate": 1,
  "receiptInvoice": {
    "id": 301,
    "uuid": "6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19",
    "type": "invoice",
    "number": "20260001",
    "clientId": 101,
    "client": {
      "name": "Acme s.r.o.",
      "type": "company",
      "subjectId": "12345678",
      "taxId": "2020123456",
      "vatId": "SK2020123456",
      "isVatPayer": true,
      "email": "billing@acme.test",
      "street": "Main Street 1",
      "city": "Bratislava",
      "zip": "81101",
      "countryId": 703,
      "country": {
        "id": 703,
        "name": "Slovakia",
        "code": "SK",
        "eu": true
      },
      "hasDeliveryAddress": true,
      "deliveryStreet": "Warehouse 9",
      "deliveryCity": "Kosice",
      "deliveryZip": "04001",
      "deliveryCountryId": 703,
      "deliveryCountry": {
        "id": 703,
        "name": "Slovakia",
        "code": "SK",
        "eu": true
      }
    },
    "issueDate": "2026-03-03",
    "dueDate": "2026-03-17",
    "deliveryDate": "2026-03-03",
    "currency": {
      "id": 1,
      "symbol": "EUR",
      "name": "Euro",
      "mark": "€"
    },
    "total": 200,
    "totalWithVat": 240,
    "toBePaid": 240,
    "status": "unpaid",
    "hasVat": true
  }
}

{
  "message": "The given data was invalid.",
  "error": "Idempotency-Key reused with different request payload",
  "errors": {}
}

{
  "message": "Too Many Attempts."
}

{
  "message": "Server Error"
}

{
  "message": "Service Unavailable"
}

Authorizations

Authorization

string

header

required

Bearer token created for a specific company in Integrations → API.

Headers

Idempotency-Key

string

Optional request identifier for safe retries. Use a unique value for each create request you want to retry safely.

Example:

"invoice-create-2026-03-03-001"

Body

application/json

Payload used to create a document payment. Only invoice, proforma, and credit-note documents are supported, and the target document must be available in the token scope.

documentType

enum<string>

required

Type of the document you are paying.

Available options:

invoice,

proforma,

credit-note

Example:

"invoice"

documentId

integer

required

ID of the document you are paying.

Example:

301

currencyId

integer

Optional currency ID from the currency reference table. If omitted, the source document currency is used.

Example:

1

currencyRate

number<float>

Exchange rate of the payment currency against EUR. If omitted, the system derives it from the final paymentDate using the previous day's rate. If provided for a currency other than EUR, the override value is used as-is. If the final payment currency is EUR, the backend always stores 1.0.

Example:

1

paymentDate

string<date>

Payment date in Y-m-d format. If omitted, today's date is used.

Example:

"2026-03-07"

paymentMethodId

integer

Optional payment method ID from the payment method reference table. If omitted, the source document payment method is used.

Example:

1

amount

number<float>

Payment amount in the payment currency. If omitted, the current remaining toBePaid amount from the source document is used. This derived amount is available only when the source document has a non-zero toBePaid; otherwise the endpoint returns 422. If sent explicitly, it can have at most 2 decimal places, its magnitude must not exceed the current toBePaid, and it must keep the same sign. The backend also accepts negative amounts, for example when settling a credit note. On storage, the sign is normalized by document type: negative absolute value for credit-note, positive absolute value for invoice and proforma.

Must be a multiple of 0.01

Example:

15.5

Response

Document payment created.

One payment of a public document.

integer

Internal payment ID.

Example:

801

documentType

enum<string>

Type of the document this payment belongs to.

Available options:

invoice,

proforma,

credit-note

Example:

"invoice"

documentId

integer

ID of the document this payment belongs to.

Example:

301

paymentMethod

object

Used payment method as a nested lookup object.

Show child attributes

currency

object

Payment currency as a nested lookup object.

Show child attributes

paymentDate

string<date>

Payment date in Y-m-d format.

Example:

"2026-03-07"

amount

number<float>

Payment amount in the payment currency. On storage, the sign is normalized by document type: negative absolute value for credit-note, positive absolute value for invoice and proforma.

Example:

15.5

currencyRate

number<float>

Exchange rate of the payment currency against EUR. If the payment currency is EUR, the backend always returns 1.0.

Example:

1

receiptInvoice

object | null

Preview of the linked payment receipt invoice, when it exists.

Show child attributes

Create document payment

curl --request POST \
  --url https://app.fintoro.sk/api/public/v1/document-payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "documentType": "invoice",
  "documentId": 301,
  "currencyId": 1,
  "currencyRate": 1,
  "paymentDate": "2026-03-07",
  "paymentMethodId": 1,
  "amount": 15.5
}
'

import requests

url = "https://app.fintoro.sk/api/public/v1/document-payments"

payload = {
    "documentType": "invoice",
    "documentId": 301,
    "currencyId": 1,
    "currencyRate": 1,
    "paymentDate": "2026-03-07",
    "paymentMethodId": 1,
    "amount": 15.5
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    documentType: 'invoice',
    documentId: 301,
    currencyId: 1,
    currencyRate: 1,
    paymentDate: '2026-03-07',
    paymentMethodId: 1,
    amount: 15.5
  })
};

fetch('https://app.fintoro.sk/api/public/v1/document-payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.fintoro.sk/api/public/v1/document-payments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'documentType' => 'invoice',
    'documentId' => 301,
    'currencyId' => 1,
    'currencyRate' => 1,
    'paymentDate' => '2026-03-07',
    'paymentMethodId' => 1,
    'amount' => 15.5
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.fintoro.sk/api/public/v1/document-payments"

	payload := strings.NewReader("{\n  \"documentType\": \"invoice\",\n  \"documentId\": 301,\n  \"currencyId\": 1,\n  \"currencyRate\": 1,\n  \"paymentDate\": \"2026-03-07\",\n  \"paymentMethodId\": 1,\n  \"amount\": 15.5\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.fintoro.sk/api/public/v1/document-payments")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"documentType\": \"invoice\",\n  \"documentId\": 301,\n  \"currencyId\": 1,\n  \"currencyRate\": 1,\n  \"paymentDate\": \"2026-03-07\",\n  \"paymentMethodId\": 1,\n  \"amount\": 15.5\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.fintoro.sk/api/public/v1/document-payments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"documentType\": \"invoice\",\n  \"documentId\": 301,\n  \"currencyId\": 1,\n  \"currencyRate\": 1,\n  \"paymentDate\": \"2026-03-07\",\n  \"paymentMethodId\": 1,\n  \"amount\": 15.5\n}"

response = http.request(request)
puts response.read_body

{
  "id": 801,
  "documentType": "invoice",
  "documentId": 301,
  "paymentMethod": {
    "id": 1,
    "name": "Bank transfer"
  },
  "currency": {
    "id": 1,
    "symbol": "EUR",
    "name": "Euro",
    "mark": "€"
  },
  "paymentDate": "2026-03-07",
  "amount": 15.5,
  "currencyRate": 1,
  "receiptInvoice": {
    "id": 301,
    "uuid": "6b1b8c9e-66e6-4fb5-b2db-6d7c7f0f8f19",
    "type": "invoice",
    "number": "20260001",
    "clientId": 101,
    "client": {
      "name": "Acme s.r.o.",
      "type": "company",
      "subjectId": "12345678",
      "taxId": "2020123456",
      "vatId": "SK2020123456",
      "isVatPayer": true,
      "email": "billing@acme.test",
      "street": "Main Street 1",
      "city": "Bratislava",
      "zip": "81101",
      "countryId": 703,
      "country": {
        "id": 703,
        "name": "Slovakia",
        "code": "SK",
        "eu": true
      },
      "hasDeliveryAddress": true,
      "deliveryStreet": "Warehouse 9",
      "deliveryCity": "Kosice",
      "deliveryZip": "04001",
      "deliveryCountryId": 703,
      "deliveryCountry": {
        "id": 703,
        "name": "Slovakia",
        "code": "SK",
        "eu": true
      }
    },
    "issueDate": "2026-03-03",
    "dueDate": "2026-03-17",
    "deliveryDate": "2026-03-03",
    "currency": {
      "id": 1,
      "symbol": "EUR",
      "name": "Euro",
      "mark": "€"
    },
    "total": 200,
    "totalWithVat": 240,
    "toBePaid": 240,
    "status": "unpaid",
    "hasVat": true
  }
}

{
  "message": "The given data was invalid.",
  "error": "Idempotency-Key reused with different request payload",
  "errors": {}
}

{
  "message": "Too Many Attempts."
}

{
  "message": "Server Error"
}

{
  "message": "Service Unavailable"
}

Overview

Endpoints

Create document payment

Supported document types

Business behavior

Authorizations

Headers

Body

Response