> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finventi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CESOP

CESOP (Central Electronic System of Payment information) is an EU wide report. Payment Service Providers must report cross-border payment data quarterly, per reportable Member State, to their national authority, which forwards it to the EU central system. This connector exposes a **REST API**: you stream payees and their payments into a submission, then hand it off to be reported to the regulatory authority.

## How it works

A submission is a reporting batch scoped to one **reporting period** (year + quarter) and one **reportable country**. You build it up incrementally and then submit it:

<Steps>
  <Step title="Create a submission">
    `POST /reports/cesop/v1/submissions` with the year, quarter, and reportable country. You get back a `submissionId` that scopes every subsequent call. Optionally include a `webhookUrl` to be notified when the submission finishes processing.
  </Step>

  <Step title="Push payees">
    `POST /reports/cesop/v1/submissions/{submissionId}/payees` with a batch of payees. Each payee carries your own `clientPayeeId`, which is echoed back and is the only identifier you use to attach payments and to update or delete the payee later.
  </Step>

  <Step title="Push payments">
    `POST /reports/cesop/v1/submissions/{submissionId}/payments` with a batch of payments. Each payment links to a payee via `payeeClientId` (that payee's `clientPayeeId`). This is the high-volume stream and can be called repeatedly.
  </Step>

  <Step title="Submit">
    `POST /reports/cesop/v1/submissions/{submissionId}:submit` hands the submission off for reporting. After this call the submission is no longer editable.
  </Step>

  <Step title="Track progress and fix errors">
    Poll `GET .../status` for the high-level state, or `GET .../report` for reported-versus-pending counts of payees, payments, and packages. `GET .../payees/errors` lists payees the authority rejected, with the error codes to fix.
  </Step>
</Steps>

While a submission is still a draft you can [delete it](/regulatory/rrc/api/cesop/delete-submission) along with everything pushed under it. Once submitted, it can no longer be deleted.

## clientPayeeId is your key

You never deal with server-assigned reference ids. Your `clientPayeeId` is the sole correlation key: it links payments to payees, addresses updates and deletions, and identifies a payee in the report and error lists. It must be unique within a submission.

## Packages

A reportable country has a maximum number of transactions per file. When a payee has more payments than that limit, the connector automatically splits it into several **packages** behind the scenes you still push it as one logical payee under one `clientPayeeId`. The submission report tells you how many packages were generated, accepted, and still awaiting a response.

## Corrections

Once a period has been reported, opening a submission for that **same period and country again** is a correction round. It reuses the same endpoints, keyed by `clientPayeeId`:

* **`POST /payees`** for adding new data new payees to the already-reported period.
* **`POST /payments`** for adding and new transactions to the already-reported period.
* **`PUT /payees/{clientPayeeId}`** for amend a payee that was already reported. If the payee was reported across several packages, the correction fans out across all of them.
* **`DELETE /payees/{clientPayeeId}`** for voiding a payee and its transactions that was already reported.

## Submission status

`status` on a submission moves through:

| Status            | Meaning                                                         |
| ----------------- | --------------------------------------------------------------- |
| `DRAFT`           | Open for pushing payees and payments; not yet submitted.        |
| `PROCESSING`      | Submitted; being reported to the regulatory authority.          |
| `ACTION_REQUIRED` | Some payees were rejected and need correcting and re-reporting. |
| `REPORTED`        | Accepted by the regulatory authority.                           |
| `FAILED`          | Reporting failed.                                               |

## Webhook

Instead of polling for status, pass a `webhookUrl` when you [create a submission](/regulatory/rrc/api/cesop/create-submission). Once the submission finishes processing, the connector calls it with a POST carrying a JSON body:

```json theme={null}
{"submissionId": "<submission id>", "status": "ACCEPTED"}
```

`status` is the CESOP validation result for the submission: `ACCEPTED` or `REJECTED`. Calls originate from the following IP addresses; whitelist them to receive the webhook.

| Environment | IP addresses                                                |
| ----------- | ----------------------------------------------------------- |
| Test        | 34.78.184.35, 35.195.129.148, 34.76.178.43, 88.119.208.29   |
| Production  | 130.211.66.226, 35.205.15.220, 104.155.69.28, 88.119.208.29 |

## Filtering support

Deciding which payments are reportable is your responsibility. The connector reports the data you send as is.
To help with filtering decisions, [check an address](/regulatory/rrc/api/cesop/check-address) resolves a free text
address and tells you whether it is in a third territory for CESOP purposes: a country outside the EU,
or an EU territory excluded from the EU VAT area (e.g. the Canary Islands). It is a helper only and not part of the
submission flow.

## Authentication

All endpoints require a bearer JWT obtained via the OAuth2 `client_credentials` grant. See [Authentication](/regulatory/rrc/authentication).

## API Reference

Explore the full API specification in the [Swagger documentation](https://api.rrc.finventi.com/reports/cesop/swagger-ui/index.html).

<Info>
  **IP Whitelisting Required:** Before you can access the Swagger documentation, your IP address must be whitelisted. Contact us to register your IP addresses.
</Info>

## Resources

<CardGroup cols={2}>
  <Card title="Submissions" icon="folder-plus" href="/regulatory/rrc/api/cesop/create-submission">
    Open a reporting batch, submit it, and track its status
  </Card>

  <Card title="Payees" icon="user-tag" href="/regulatory/rrc/api/cesop/push-payees">
    Push, update, and delete the payees you report
  </Card>

  <Card title="Payments" icon="money-bill-transfer" href="/regulatory/rrc/api/cesop/push-payments">
    Stream the payments linked to each payee
  </Card>

  <Card title="Report" icon="chart-line" href="/regulatory/rrc/api/cesop/get-submission-report">
    Reported-versus-pending counts and per-payee state
  </Card>
</CardGroup>