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:1
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.2
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.3
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.4
Submit
POST /reports/cesop/v1/submissions/{submissionId}:submit hands the submission off for reporting. After this call the submission is no longer editable.5
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.clientPayeeId is your key
You never deal with server-assigned reference ids. YourclientPayeeId 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 oneclientPayeeId. 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 byclientPayeeId:
POST /payeesfor adding new data new payees to the already-reported period.POST /paymentsfor 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:
Webhook
Instead of polling for status, pass awebhookUrl when you create a submission. Once the submission finishes processing, the connector calls it with a POST carrying a JSON body:
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.
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 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 OAuth2client_credentials grant. See Authentication.
API Reference
Explore the full API specification in the Swagger documentation.IP Whitelisting Required: Before you can access the Swagger documentation, your IP address must be whitelisted. Contact us to register your IP addresses.
Resources
Submissions
Open a reporting batch, submit it, and track its status
Payees
Push, update, and delete the payees you report
Payments
Stream the payments linked to each payee
Report
Reported-versus-pending counts and per-payee state