Obsługa płatności

Raportowanie płatności użytkownika do BillTech

Parametry zapytania

PUT /api/liabilities/{liabilityId}/amount-paid HTTP/1.1

{
  "liabilityId": "1aed94e1-3a30-4410-ad98-58e1e9a22aec",
  "amount": 101.99
}

nazwa	opis
liabilityId: string	Identyfikator opłacanej faktury
amount: number	Sumaryczna kwota wszystkich płatności za daną fakturę

Raportowanie kolejnych płatności

Powyższy endpoint pozwala na wprowadzenie sumarycznej kwoty płatności za wskazaną fakturę.

Każde zapytanie z kwotą większą niż obecna powoduje nadpisanie starej kwoty i stworzenie nowej płatności równej różnicy kwot między nową a starą sumaryczną kwotą płatności

Dotychczasowa suma płatności jest zwracana poprzez zmienną clientAmountPaid.
W przypadku ich braku dla wskazanej faktury pole clientAmountPaid ma wartość null.

Zwroty

Zmniejszenie sumarycznej kwoty płatności za wskazaną fakturę zostanie potraktowane jako zwrot w wysokości różnicy oryginalnej sumarycznej kwoty i raportowanej.

Rekoncyliacja płatności

Dla klientów raportujących o płatnościach użytkowników do BillTech udostępniony jest mechanizm rekoncyliacji płatności.

Decyzją o jego stosowaniu jest korzystanie ze zwracanego dla faktur pola calculatedAmountToPay zamiast amountToPay.

Motywacja istnienia Systemu Rekoncyliacji

Systemy dostawców faktur stosują dwie główne metody rozliczania płatności:

1. Rozliczenie płatności na fakturę wskazaną w tytule przelewu
2. Przeksięgowanie płatności na najstarszą zaległą fakturę

Zlecenie płatności za część faktur na koncie może zatem skutkować rozbieżnością pomiędzy tym, co zostało zlecone do zapłacenia w BT API (najnowsza z dostępnych faktur) a tym, co zostało uznane za opłacone przez dostawcę (najstarsza, zaległa faktura) stosującego drugą metodę rozliczania.

System Rekoncyliacji

W celu uniknięcia powyższego problemu zalecamy korzystanie z tzw. Systemu Rekoncyliacji. To rozwiązanie ma za zadanie przeklasyfikowanie środków z płatności zleconych za pośrednictwem BillTech na zobowiązania rozliczone przez dostawców.

Odpytanie BillTech API o listę faktur przypisanych do danego konta dla każdej faktury zwraca pola calculatedAmountToPay oraz amountToPay.

Pierwsze z nich to kwota pozostała do opłacenia, która uwzględnia przeksięgowania stosowane w systemie dostawcy. Jej przeliczenie następuje w momencie zaraportowania płatności do BillTech. Pobieranie wartości pozostałej do opłacenia z pola calculatedAmountToPay oznacza korzystanie z Systemu Rekoncyliacji i pozwala na prezentowanie stanu płatności spójnego ze stanem faktycznym.

W przypadku rezygnacji z korzystania z Systemu Rekoncyliacji (pobieranie informacji nt. pozostałej kwoty do opłacenia z pola amountToPay) mogą występować rozbieżności wynikające ze stosowanej przez dostawcę metody rozliczania płatności.

caution

Pomimo tego, że API zwraca oba wskazane pola, należy korzystać tylko z jednej z powyższych wartości, zgodnie z decyzją o korzystaniu, bądź nie, z Systemu Rekoncyliacji.

Klasyfikacja płatności

W celu poinformowania klienta, o całościowym lub częściowym przeksięgowaniu płatności na rzecz innych faktur, BillTech przy każdej fakturze zwraca informację w polu reclassified. Możliwe wartości to false i true.

Wykaz pól istotnych ze względu na obsługę płatności zwracanych dla faktur

GET /api/accounts/{accountId}/liabilities

Przykład odpowiedzi, wycinek zawierający kluczowe dane płatności dla pojedyńczej faktury

[
    {
        "liabilityId": "1a9c486f-57bb-4b06-a8ea-f1aaf6b79752",
        "title": "FV XII 2021"
        "amount": 18.81,
        "amountToPay": 18.81,
        "calculatedAmountToPay": 0.00,
        "paymentStatus": "KNOWN",
        "clientPaymentStatus": "KNOWN",
        "clientAmountPaid": 18.81,
        "reclassified": true,
        ...
    }
]

Kluczowe dla obsługi płatności pola zwracane na liście faktur:

nazwa	opis
title: string	Tytuł faktury pobrany z systemu dostawcy wykorzystywany jako tytuł płatności
amountToPay: number	Kwota do zapłaty pobrana bezpośrednio z systemu dostawcy
calculatedAmountToPay: number	Kwota pozostała do opłacenia z uwzględnieniem poprzednich płatności wykonywanych (i raportowanych do BillTech) przez klienta
clientAmountPaid: number	Sumaryczna kwota płatności za daną fakturę zaraportowanych do BillTech przez klienta
paymentStatus: KNOWN / UNKNOWN	Dostępność stanu opłacenia faktury. Niektóre z systemów dostawców nie udostępniają informacji pozwalających stwierdzić stanu opłacenia faktury
reclassified: false / true	Flaga wskazująca stan księgowania płatności za daną fakturę. Wartość true oznacza, że co najmniej część płatności została zaksięgowana na poczet innej faktury

Relacja paymentStatus z amountToPay/calculatedAmountToPay

• Gdy wartością paymentStatus jest UNKNOWN:

  • amountToPay == null, nie jest możliwe pobranie z systemu dostawcy kwoty pozostałej do zapłacenia.
  • calculatedAmountToPay początkowo ustawiane jest na wartość amount, wpływa na nie raportowanie kolejnych płatności.

• Gdy wartością paymentStatus jest KNOWN:

  • amountToPay != null, jest ona pobierana bezpośrednio z systemu dostawcy faktur
  • calculatedAmountToPay początkowo ustawiane jest na wartość amountToPay, wpływa na nie raportowanie kolejnych płatności.