Status Notifications (events)

Receive real-time status events from Ropo One into your system.

Use this when you need push-based updates. Use Status Updates when you prefer polling.

• note that polling service doesn't include as wide variety of different actions as status notification service does

Please note:

• Ropo may add new fields to the messages described in this document without separately announcing them.

• Changes which affects to current field content or naming or any other thing that breaks backward compatibility are announced as an own change process and are not implemented in production until users have had enough time to react.

What you receive

Ropo One sends HTTP POST requests to your endpoint. Each request contains one event batch.

One batch can include multiple message types. One batch contains max 500 messages.

Setup checklist

1

Expose a webhook endpoint

Accept POST requests over HTTPS. Parse JSON.

Make the handler idempotent. Use id to dedupe.

2

Choose authentication

Pick either OAuth2 client credentials or Basic Auth. Share the needed details with Ropo.

3

Return the right HTTP status codes

Return 2xx when you have stored the events. Return 4xx for permanent validation errors. Return 5xx for transient errors.

Authentication

OAuth2 (client_secret_post)

Ropo fetches an access token from your token endpoint. Ropo then uses it as a Bearer token for webhook delivery.

Share these values with Ropo:

• Token URL

• Client ID

• Client secret

• Webhook service endpoint (your receiver URL)

• Scope (if your token endpoint requires it)

Token request (from Ropo to you):

POST <token-url>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=<scope>&client_id=<client-id>&client_secret=<client-secret>

Expected token response (from you to Ropo):

{
  "token_type": "Bearer",
  "access_token": "<token>",
  "expires_in": 3600
}

Basic Auth

Envelope format

Every webhook payload uses the same envelope:

• created_at (string): message creation time in ISO-8601 format.

• id (string): unique message/batch id.

• data (object): one or more arrays by message type.

data can contain any combination of these arrays:

• delivery

• lcstatus

• payment

• contract

• creditnote

• duedateupdate

• disconnect

• reconnect

Ropo may add new fields without separate notice. Ignore unknown fields to stay forward-compatible.

Common identification rules

Most message types identify the case using either:

• invoicenumber

• documentid (your additional identifier for the document in addition to invoice number)

• jobid (Ropo One internal identifier)

Some messages all three. Don’t assume documentid is always present.

cid is the Ropo One profile id. It is mandatory in all message types.

Message types

Sample payloads

Examples are trimmed for readability. Expect more fields in production.

Single message type (delivery):

{
  "created_at": "2022-05-10T11:36:00+00:00",
  "id": "a0a348f7-764f-40f8-9fc0-d1b76012ca47",
  "data": {
    "delivery": [
      {
        "jobid": 123637,
        "cid": 987654,
        "distributionchannel": "b2b",
        "documentid": "2728282",
        "invoicenumber": "38938",
        "status": "received",
        "statustime": "2022-05-10 11:12:36",
        "description": "document received with notes.",
        "notes": [{ "note": "Check postal address." }]
      }
    ]
  }
}

Batch with multiple message types:

{
  "created_at": "2023-11-03T12:10:28+02:00",
  "id": "bfe59147-96be-47e0-a288-fe4ff8b70fef",
  "data": {
    "delivery": [{ "jobid": 123637, "cid": 987654, "status": "delivered", "statustime": "2022-05-10 12:36:00" }],
    "lcstatus": [{ "code": 2, "cid": 987654, "jobid": 23231, "time": "2022-05-10 10:27:41" }],
    "payment": [{ "cid": 987654, "jobid": 423145, "time": "2025-09-26 18:27:41", "amount": 50.0 }]
  }
}

Delivery status (data.delivery[])

Tells you how document delivery progressed.

Fields you’ll use most:

• status: received | rejected | delivered | error

• statustime: when the status changed

• distributionchannel: post | b2b | peppol | email | b2c

• description: extra details

• notes[]: optional notes (received use case)

• errors[]: optional errors (rejected/error use cases)

Delivery status values

• received: document received by Ropo One

• rejected: rejected on import. Check description and errors[]

• delivered: delivered to recipient / next party

• error: delivery failed. Check description and errors[]

Lifecycle status (data.lcstatus[])

Tells you when a case moved to a new lifecycle phase.

Fields you’ll use most:

• code: lifecycle code

• status: lifecycle text (often English)

• time: when the status change happened

• paydate: original due date

• currentpaydate: current due date

• opencapital, interest, expenses: open amounts by type (optional)

Lifecycle status codes

Most commonly used status codes:

0   Invoicing
1   Reminder
2   Debt collection
11  Draft
16  Legal collection consideration
17  Post-collection
63  Writ of summons sent to district court
101 Paid
102 Job terminated

Full list of possible status codes

• This list can grow. Store the numeric code and treat status as informational.

0   Invoicing
1   Reminder
2   Debt collection
6   Debt rescheduling
11  Draft
12  Query – protesting
14  Protested
15  Bankruptcy threat payment notification
16  Legal collection consideration
17  Post-collection
41  Payment plan
55  International legal collection consideration
61  Query – legal collection
63  Writ of summons sent to district court
65  Waiting transfer to enforcement
67  Query – distraint
68  Waiting – estate inventory deed
71  Error – address details
80  Disputed
81  Under review
85  Ropo Legal handling case
86  Query – client's response
89  Address verification
98  Message
101 Paid
102 Job terminated
103 Credit loss
104 Credit invoice
108 Invoice purchasing – sold
110 Under restructuring proceedings
111 Under bankruptcy proceedings
112 In enforcement
121 In international collection
150 Cut-off warning
200 Query – payment reminder
202 Query – identification information
203 Payment plan not followed
208 Regression
211 Query – draft
214 Query – debt collection
300 Invoice (operating)
301 Document (operating)
401 Waiting – funding
402 Invoicing – funding

Payment (data.payment[])

Tells you about payments received and booked in Ropo One.

Key points:

• paydate is deprecated.

• Use paymentdate, accountdate, and settlementdate for booking clarity.

  • paymentdate = Day when payment was made.

  • accountdate = Day when payment was booked to account

  • settlementdate = Day when payment was paid out from Ropo

• openamount includes capital + client expenses + interest.

• amountbreakdown and openamountbreakdown includes detailed view what receivable types were paid and are still open.

Contract (data.contract[])

Tells you about contract data changes, when contract updates are part of the agreed lifecycle.

Key fields:

• contract_no (mandatory)

• contractstatus (mandatory, example: active)

• termination_date and terminationterm may be present if termination is calculated

Credit note (data.creditnote[])

Tells you when a credit note is:

• allocated to a debit invoice

• unallocated (allocation removed)

• refunded to the end customer

Notes:

• Allocation/unallocation may reference invoices via bill numbers and/or job IDs.

• Credit notes allocated based on allocation info received from the client are not reported.

Due date update (data.duedateupdate[])

Sent when due date changes in Ropo One.

Important fields:

• currentpaydate: the new due date

• source: why/how the update happened

• contract[]: optional list of contract numbers (can be 1..n)

Due date update source values

• restapi: updated from an external source via Ropo REST API

• online: updated by end customer in Ropo online service

• aspa_end_customer_request: updated by Ropo customer service on end customer request

• aspa_other_reason: updated by Ropo customer service for other reasons

• einvoice_error: updated after e-invoice negative ack, then fixed and resent

Disconnect / reconnect (data.disconnect[], data.reconnect[])

Sent when a process recognizes a disconnect/reconnect action is needed.

Both contain:

• usageplacecode (mandatory)

• contract_no (mandatory)

• invoices[] with invoice identifiers (jobid, invoicenumber, optional documentid)

Disconnect may include disconnectiondate.

Error response body (optional)

You can return a problem details body with non-2xx responses. RFC 7807 is recommended.

{
  "type": "https://example.com/problems/invalid-payload",
  "title": "Invalid payload",
  "status": 400,
  "detail": "Missing required field: data.delivery[0].cid"
}

Webhook definition (OpenAPI)

Status notification service

Status notification service

Payload

application/json

Status information provided from Ropo One.

createdstring · dateOptional

Event creation timestamp in ISO8601 format

Example: 2019-08-12T14:36:00+00:00

idstringOptional

Event identification

Example: e69f55fe-46c4-45cf-ab16-85da60b63884

dataone ofOptional

or

nullOptional

Responses

200

OK

No content

Payload

{
  "created": "2019-08-12T14:36:00+00:00",
  "id": "e69f55fe-46c4-45cf-ab16-85da60b63884",
  "data": {
    "contract": [
      {
        "contract_no": "123456",
        "jobid": "234567",
        "cid": "12345",
        "name": "Network contract",
        "startdate": "2017-06-01",
        "enddate": "2018-06-01",
        "contractstatus": "closed",
        "type": "insurance",
        "termination_date": "2022-06-01",
        "terminationterm": "14",
        "description": "Termination date was updated",
        "customernumber": "text"
      }
    ],
    "delivery": [
      {
        "jobid": "12345",
        "cid": "12345",
        "documentid": "1568967695dfc8d393a4bd4cc5bb258eff2bb3cea4",
        "status": "delivered",
        "statustime": "2019-08-12T14:36:00+00:00",
        "description": "Recipient not found or not active",
        "distributionchannel": "b2b",
        "invoicenumber": "12345",
        "customernumber": "text"
      }
    ],
    "lcstatus": [
      {
        "jobid": "12345",
        "cid": "12345",
        "documentid": "1568967695dfc8d393a4bd4cc5bb258eff2bb3cea4",
        "status": "delivered",
        "code": "0",
        "time": "2019-08-12T14:36:00+00:00",
        "description": "Recipient not found or not active",
        "paydate": "2022-06-15",
        "currentpaydate": "2022-06-30",
        "invoicenumber": "12345",
        "interest": 7,
        "expenses": 50,
        "opencapital": 250,
        "source": "online",
        "contract": [
          {
            "contract_no": "text"
          }
        ],
        "customernumber": "text"
      }
    ],
    "payment": [
      {
        "jobid": "12345",
        "cid": "12345",
        "documentid": "1568967695dfc8d393a4bd4cc5bb258eff2bb3cea4",
        "amount": "30.00",
        "amountbreakdown": {
          "capital": "30.00",
          "interest": "1.20",
          "expenses": 5,
          "cashdiscount": "0.50"
        },
        "openamount": "30.00",
        "openamountbreakdown": {
          "capital": "30.00",
          "interest": "1.20",
          "expenses": 5,
          "cashdiscount": "0.50"
        },
        "type": "2",
        "time": "2019-08-12T14:36:00+00:00",
        "description": "Paid to Ropo",
        "reference": "1234567",
        "invoicenumber": "1234567",
        "paymentdate": "2022-06-15",
        "accountdate": "2022-06-15",
        "settlementdate": "2022-06-15",
        "customernumber": "text"
      }
    ],
    "duedateupdate": [
      {
        "jobid": "12345",
        "cid": "12345",
        "documentid": "1568967695dfc8d393a4bd4cc5bb258eff2bb3cea4",
        "status": "delivered",
        "code": "0",
        "time": "2019-08-12T14:36:00+00:00",
        "description": "Recipient not found or not active",
        "paydate": "2022-06-15",
        "currentpaydate": "2022-06-30",
        "invoicenumber": "12345",
        "interest": 7,
        "expenses": 50,
        "opencapital": 250,
        "source": "online",
        "contract": [
          {
            "contract_no": "text"
          }
        ],
        "customernumber": "text"
      }
    ],
    "creditnote": [
      {
        "creditjobid": "12345",
        "creditbillnum": "2019-08-12T14:36:00+00:00",
        "debitjobid": "12345",
        "debitbillnum": "2019-08-12T14:36:00+00:00",
        "cid": "12345",
        "amount": "2019-08-12T14:36:00+00:00",
        "time": "2019-08-12T14:36:00+00:00",
        "type": "2019-08-12T14:36:00+00:00",
        "description": "Recipient not found or not active",
        "customernumber": "text"
      }
    ],
    "disconnect": [
      {
        "customernumber": "12345",
        "usageplacecode": "2728282",
        "contract_no": "co383838",
        "invoices": [
          {
            "invoicenumber": "12345",
            "jobid": "12345",
            "cid": "12345",
            "documentid": "1568967695dfc8d393a4bd4cc5bb258eff2bb3cea4"
          }
        ],
        "time": "2022-05-10 12:36:00",
        "description": "Disconnect usage place.",
        "disconnectiondate": "2022-05-10"
      }
    ],
    "reconnect": [
      {
        "customernumber": "12345",
        "usageplacecode": "2728282",
        "contract_no": "co383838",
        "invoices": [
          {
            "invoicenumber": "12345",
            "jobid": "12345",
            "cid": "12345",
            "documentid": "1568967695dfc8d393a4bd4cc5bb258eff2bb3cea4"
          }
        ],
        "time": "2022-05-10 12:36:00",
        "description": "Disconnect usage place."
      }
    ],
    "creditloss": [
      {
        "jobid": "12345",
        "cid": "12345",
        "documentid": "1568967695dfc8d393a4bd4cc5bb258eff2bb3cea4",
        "invoicenumber": "12345",
        "time": "2019-08-12 14:36",
        "amount": 250,
        "description": "Creditloss happened due to non payment",
        "reason": "text",
        "reference": "text",
        "type": "suspected",
        "amountbreakdown": {
          "capital": 250,
          "creditloss": 250,
          "suspected_creditloss": 250
        },
        "customernumber": "text"
      }
    ]
  }
}