Enrichment with payment advice using the API

Before you start

• The payment terms are automatically generated from each invoice issued. Refer to issue invoices to start generating invoices and their payment terms.

Steps

1. List payment terms

Get the invoices payment terms by calling GET /payment_terms endpoint filtering by the desired parameters. Check the pagination to understand how list of resources work.

Response

200 OK

{
  "cursor": "Q3VyaW9zaXR5IEtpbGxlZCB0aGUgQ2F0Cg==",
  "data": [
    {
      "id": "ptm_4wt0wrfqwz0vkatave0fkjg046",
      "status": "suggested",
      "transactions": {
        "suggested": [
          {
            "id": "trx_4gvr0vpst6kvb9azdbafgkdn5z",
            "amount": 18290,
            "currency": "EUR",
            "booking_at": "2023-09-01T12:32:12.321Z",
            [...]
          }
        ],
        "matched": []
      }
    },
    {
      "id": "ptm_4g7mp66fzn6aa9qg0rtc44ccn2",
      "status": "confirmed",
      "transactions": {
        "suggested": [],
        "matched": [
          {
            "id": "trx_4e93cxe7r0spde8gkz5vd694cq",
            "amount": 22300,
            "currency": "EUR",
            "booking_at": "2025-03-01T22:05:48.479Z",
            [...]
          }
        ]
      },
      }
    },
    {
      "id": "ptm_4jjsbep3fkzzmce9wt1k0na8cy",
      "status": "unmatched",
      "transactions": {
        "suggested": [],
        "matched": []
      },
      [...]
    },
    [...]
  ]
}

2. Get payment terms details

You can get the extended information of each payment term by calling GET /payment_terms/{payment_term_id} endpoint.

In this scenario, the {payment_term_id} used from previous step is ptm_4wt0wrfqwz0vkatave0fkjg046 to confirm or reject the suggested reconciliation after reviewing all the details.

Response

200 OK

{
  "id": "ptm_4wt0wrfqwz0vkatave0fkjg046",
  "status": "suggested",
  "transactions": {
    "suggested": [
      {
        "id": "trx_4gvr0vpst6kvb9azdbafgkdn5z",
        "amount": 18290,
        "currency": "EUR",
        "booking_at": "2023-09-01T12:32:12.321Z",
        "payment_method": {
          "type": "external_bank_transfer"
        },
        "counterparty": {
          "id": "acc_4j8mcwzgcpx8j53qw5jaxp5w4y",
          "legal_name": "Wildcat Pumps GmbH",
          "bank_account": {
            "account_number": {
              "type": "iban",
              "value": "DE92120700000532013001"
            }
          }
        }
      }
    ],
    "matched": []
  }
}

3. Confirm payment term match

For suggested transactions, you can confirm the match between the invoice payment term and the bank transaction by calling POST /payment_terms/{payment_term_id}/transactions/{transaction_id}/confirm endpoint.

In this scenario, the {payment_term_id} again, from previous steps, is ptm_4wt0wrfqwz0vkatave0fkjg046 and the {transaction_id} is the one suggested trx_4gvr0vpst6kvb9azdbafgkdn5z.

4. Reject payment term match

If the suggested transaction is a false positive, you can reject that match between the invoice payment term and the bank transaction and remove the relation between them by calling POST /payment_terms/{payment_term_id}/transactions/{transaction_id}/reject endpoint.

In this scenario, the {payment_term_id} again, from previous steps, is ptm_4wt0wrfqwz0vkatave0fkjg046 and the {transaction_id} is also the one suggested trx_4gvr0vpst6kvb9azdbafgkdn5z.