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
Authentication
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
}Ropo uses HTTP Basic Auth for webhook delivery.
Share these values with Ropo:
User ID
Password
Webhook service endpoint (your receiver URL)
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:
deliverylcstatuspaymentcontractcreditnotecreditlossduedateupdatedisconnectreconnecttelecomdisconnecttelecomreconnect
Common identification rules
Most message types identify the case using either:
invoicenumberdocumentid(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
Delivery status (data.delivery[])
Tells you how document delivery progressed.
Fields you’ll use most:
status:received|rejected|delivered|errorstatustime: when the status changeddistributionchannel:Finland
post|b2b|peppol|email|b2c|kivra|omapostiSweden
post|b2b|peppol|email|b2c|kivraNorway
post|b2b|peppol|email|b2c|digipost
description: extra detailsnotes[]: optional notes (received use case)errors[]: optional errors (rejected/error use cases)
Lifecycle status (data.lcstatus[])
Tells you when a case moved to a new lifecycle phase.
Fields you’ll use most:
code: lifecycle codestatus: lifecycle text (often English)time: when the status change happenedpaydate: original due datecurrentpaydate: current due dateopencapital,interest,expenses: open amounts by type (optional)
Payment (data.payment[])
Tells you about payments received and booked in Ropo One.
Key points:
paydateis deprecated.Use
paymentdate,accountdate, andsettlementdatefor booking clarity.paymentdate= Day when payment was made.accountdate= Day when payment was booked to accountsettlementdate= Day when payment was paid out from Ropo
openamountincludes capital + client expenses + interest.amountbreakdownandopenamountbreakdownincludes 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_dateandterminationtermmay be present if termination is calculated
Credit note (data.creditnote[])
Tells you when a credit note is:
allocatedto a debit invoiceunallocated(allocation removed)refundedto 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.
Credit loss (data.creditloss[])
Tells you about credit loss related actions.
Key fields:
typesuspected: suspected bad receivable before actual credit loss. Used only in Sweden.creditloss: receivable has become bad debt.change: bad debt receivable changed, for example after a payment.
amountbreakdown: amounts related to the credit loss actionreason: reason for the credit lossOTHERDECEASEDINDIGENTUNKNOWNRESTRUCTURINGDEBT_RESCHEDULINGBANKRUPTCYSMALL_RECEIVABLENOCHANGEDISPUTINGDISPUTEDTIMEBASED
Due date update (data.duedateupdate[])
Sent when due date changes in Ropo One.
Important fields:
currentpaydate: the new due datesource: why/how the update happenedcontract[]: optional list of contract numbers (can be 1..n)
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, optionaldocumentid)
Disconnect may include disconnectiondate.
Telecom disconnect / reconnect (data.telecom_disconnect[], data.telecom_reconnect[])
Sent when a process recognizes a Telecom disconnect/reconnect action is needed.
Relevant fields:
customernumber: points to the end customer whose telecom subscriptions should be disconnected or reconnectedtime: timestamp when it was recognized that the subscription should be disconnected or reconnected
Error response body (optional)
You can return a problem details body with non-2xx responses. RFC 7807 is recommended.
Webhook definition (OpenAPI)
Status notification service
Status information provided from Ropo One.
Event creation timestamp in ISO8601 format
2019-08-12T14:36:00+00:00Event identification
e69f55fe-46c4-45cf-ab16-85da60b63884OK
No content
Payload
{
"created_at": "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",
"product": "Home insurance",
"description": "Termination date was updated",
"customernumber": "text"
}
],
"delivery": [
{
"jobid": 12345,
"cid": 12345,
"documentid": "1568967695dfc8d393a4bd4cc5bb258eff2bb3cea4",
"status": "delivered",
"statustime": "2019-08-12 14:36:00",
"description": "Recipient not found or not active",
"distributionchannel": "b2b",
"notes": [
{
"note": "Check postal address."
}
],
"errors": [
{
"error": "Postal address missing."
}
],
"invoicenumber": "12345",
"customernumber": "text"
}
],
"lcstatus": [
{
"jobid": "12345",
"cid": "12345",
"documentid": "1568967695dfc8d393a4bd4cc5bb258eff2bb3cea4",
"status": "delivered",
"code": "0",
"time": "2019-08-12 14:36: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-12 14:36: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-12 14:36: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": "52762781",
"debitjobid": 12345,
"debitbillnum": "436323434",
"cid": 12345,
"amount": "100.00",
"time": "2019-08-12 14:36:00",
"type": "allocated",
"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."
}
],
"disconnect_telecom": [
{
"customernumber": "10599938",
"time": "2026-04-23 03:40:17",
"description": "Katkaisupyyntö"
}
],
"reconnect_telecom": [
{
"customernumber": "10599938",
"time": "2026-04-23 03:40:17",
"description": "Connection request"
}
],
"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"
}
]
}
}Last updated
Was this helpful?

