Invoices | Set Invoice Transaction

Invoice Transaction Endpoint

This document provides guidance on using the API to add a payment transaction to an existing invoice through the set_invoice_transaction endpoint. Payment methods are identified by the NUMERIC codes the system uses internally — the full map is documented below and must be used as-is. After each transaction the platform recalculates the invoice totals and status (a fully covered invoice becomes paid).

API ENDPOINT FOR ADDING INVOICE TRANSACTIONS

To add a payment, provide your API credentials, the invoice (invoice_id or reference), the amount in the invoice currency and the numeric payment_type. The response returns the created transaction and the refreshed invoice totals and status.

Endpoint and Method

  • Endpoint: https://easycms.fi/public_api/set_invoice_transaction/
  • Method: POST

Parameters | Payload

API Authentication Parameters

  • TOKEN (api_key): Your unique API key for authentication. How to Create API Credentials.
  • username: Your login username.
  • password: Your login password.
  • account: Your specific account ID.

Transaction Parameters

  • invoice_id (integer): The numeric invoice id (either this or reference is required).
  • reference (string): The invoice payment reference number (either this or invoice_id is required).
  • amount (required, number > 0): The payment amount in the invoice's own currency. Partial payments are supported — send each payment as its own transaction call.
  • payment_type (required, integer): The numeric payment-method code from the map below (the same numeric codes the system uses everywhere, e.g. in the cash-register integration and the admin transaction list):
payment_type payment_method
0 bank_transfer
1 cash
2 card
3 online_banking
4 e_invoice
5 paypal
6 google_wallet
7 stripe
20 cash_on_pickup
21 cash_on_delivery
25 factoring
30 other_payments
100 customer_balance_credit_transfer
110 refund_from_invoice_total
  • date (optional): The payment date, Y-m-d or dd.mm.YYYY (default: now).

Notes:

  • Transactions created through the API are recorded as automatic entries (entry_type 1) attributed to your API user, so the admin transaction list shows where each payment came from.
  • After every transaction the platform recomputes total_paid, total_due and the invoice status automatically: the invoice flips to paid when the total is covered, is_partially_paid while it is not, and is_over_paid when it is exceeded.
  • Transactions cannot be added to a cancelled invoice.

Handling Responses

The transaction object echoes what was recorded (with the resolved payment_method name), and the invoice object carries the refreshed total_paid, total_due and the new status (paid when fully covered, otherwise open with is_partially_paid).



Call Examples in Different Languages


curl -X POST 'https://easycms.fi/public_api/set_invoice_transaction' \
-H 'Authorization1: TOKEN' \
-d 'username=USERNAME&password=PASSWORD&account=ACCOUNT_ID&invoice_id=1042&amount=380.63&payment_type=2'

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://easycms.fi/public_api/set_invoice_transaction",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => http_build_query(['username' => 'USERNAME', 'password' => 'PASSWORD', 'account' => 'ACCOUNT_ID', 'invoice_id' => '1042', 'amount' => '380.63', 'payment_type' => '2']),
  CURLOPT_HTTPHEADER => array("Authorization1: TOKEN"),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

import requests
url = "https://easycms.fi/public_api/set_invoice_transaction"
headers = {"Authorization1": "TOKEN"}
payload = {'username': 'USERNAME', 'password': 'PASSWORD', 'account': 'ACCOUNT_ID', 'invoice_id': '1042', 'amount': '380.63', 'payment_type': '2'}
response = requests.post(url, headers=headers, data=payload)
print(response.text)

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://easycms.fi/public_api/set_invoice_transaction"))
    .headers("Authorization1", "TOKEN")
    .POST(HttpRequest.BodyPublishers.ofString("username=USERNAME&password=PASSWORD&account=ACCOUNT_ID&invoice_id=1042&amount=380.63&payment_type=2"))
    .build();
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

const https = require('https');
const data = new URLSearchParams({ 
  "username": "USERNAME",
  "password": "PASSWORD",
  "account": "ACCOUNT_ID",
  "invoice_id": "1042",
  "amount": "380.63",
  "payment_type": "2",
}).toString();
const options = {
  hostname: 'easycms.fi',
  path: '/public_api/set_invoice_transaction',
  method: 'POST',
  headers: {
    'Authorization1': 'TOKEN',
    'Content-Type': 'application/x-www-form-urlencoded',
    'Content-Length': data.length
  }
};
const req = https.request(options, (res) => {
  let data = '';
  res.on('data', (chunk) => { data += chunk; });
  res.on('end', () => { console.log(data); });
});
req.on('error', (e) => { console.error(e); });
req.write(data);
req.end();

import React, { useEffect, useState } from 'react';
function App() {
  const [responseText, setResponseText] = useState('');
  useEffect(() => {
    const fetchData = async () => {
      try {
        const response = await fetch('https://easycms.fi/public_api/set_invoice_transaction', {
          method: 'POST',
          headers: {'Authorization1': 'TOKEN', 'Content-Type': 'application/x-www-form-urlencoded'},
          body: new URLSearchParams({"username": "USERNAME", "password": "PASSWORD", "account": "ACCOUNT_ID", "invoice_id": "1042", "amount": "380.63", "payment_type": "2"}).toString()
        });
        const data = await response.text();
        setResponseText(data);
      } catch (error) {
        console.error(error);
      }
    };
    fetchData();
  }, []);
  return (
{responseText}
); } export default App;

// Kotlin example requires using a third-party library like OkHttp for POST requests with a body
// Kotlin Example using OkHttp for POST request
import okhttp3.OkHttpClient
import okhttp3.FormBody
import okhttp3.Request

fun main() {
    val client = OkHttpClient()

    val formBody = FormBody.Builder()
        .add("username", "USERNAME")
        .add("password", "PASSWORD")
        .add("account", "ACCOUNT_ID")
        .add("invoice_id", "1042")
        .add("amount", "380.63")
        .add("payment_type", "2")
        .build()

    val request = Request.Builder()
        .url("https://easycms.fi/public_api/set_invoice_transaction")
        .post(formBody)
        .addHeader("Authorization1", "TOKEN")
        .build()

    client.newCall(request).execute().use { response ->
        if (!response.isSuccessful) throw IOException("Unexpected code $response")

        println(response.body?.string())
    }
}

using System;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
    static async Task Main()
    {
        var token = "TOKEN";
        var content = new FormUrlEncodedContent(new[]
        {
            new KeyValuePair("username", "USERNAME"),
            new KeyValuePair("password", "PASSWORD"),
            new KeyValuePair("account", "ACCOUNT_ID"),
            new KeyValuePair("invoice_id", "1042"),
            new KeyValuePair("amount", "380.63"),
            new KeyValuePair("payment_type", "2")
        });
        using (var httpClient = new HttpClient())
        {
            httpClient.DefaultRequestHeaders.Add("Authorization1", token);
            var response = await httpClient.PostAsync("https://easycms.fi/public_api/set_invoice_transaction", content);
            if (response.IsSuccessStatusCode)
            {
                var responseData = await response.Content.ReadAsStringAsync();
                Console.WriteLine(responseData);
            }
            else
            {
                Console.WriteLine($"Error: {response.StatusCode}");
            }
        }
    }
}

Handling Endpoint Results

When you make a request to the endpoint, you receive a JSON response containing various keys and values. Here's an explanation of the response keys and their meanings:


{
    "OUTPUT": {
        "response_type": "success",
        "message": "transaction_was_added_successfully",
        "transaction": {
            "transaction_id": "c1d0f2e9-5b7a-4c31-9f22-6a0b1c2d3e4f",
            "invoice_id": 1042,
            "payment_type": 2,
            "payment_method": "card",
            "amount": 380.63,
            "date": "2026-10-07 09:11:04",
            "entry_type": 1
        },
        "invoice": {
            "invoice_id": 1042,
            "reference": "10753096392167",
            "total": 380.63,
            "total_paid": 380.63,
            "total_due": 0,
            "status": "paid",
            "status_flags": []
        }
    },
    "INFO": { "start": 0, "limit": 50, "count": 1, "total_count": 1, "tip": "", "docs": "https://easycms.fi/DOCUMENTATION/bt5/set_invoice_transaction" }
}
    

Error Handling

Here are the possible error messages and their meanings:

  • invoice_id_or_reference_must_be_provided_via_api: Neither invoice_id nor reference was sent.
  • invoice_not_found: No live invoice matches the id/reference in this account.
  • invoice_is_cancelled_transactions_cannot_be_added: The invoice is cancelled.
  • payment_type_must_be_one_of_the_documented_numeric_values_...: The payment_type is not in the numeric map (the message lists the valid codes).
  • amount_must_be_a_positive_number: The amount is missing, not numeric or not positive.
  • UN-AUTHORIZED - ...: Authentication failed (wrong TOKEN/username/password/account).