Recon Service API

Reconciliation runs, settlements, disbursements, exceptions, deductions, risk holds, rules, and merchant management

The Recon Service is the back-office reconciliation engine for 505pay. It ingests settlement files from PSPs, matches them against payment intents, flags exceptions, manages the disbursement approval workflow, and produces the financial reports that treasury and finance rely on.

Base URLs

Environment	Hostname
Sandbox	`https://sandbox.505pay.link`
Production	`https://api.505pay.link`

All endpoints require Authorization: Bearer <jwt> issued by the Auth Service with the appropriate recon.* permissions. The Recon Service is operator-facing — end-customers do not interact with it directly.

Reconciliation run lifecycle

A reconciliation run is created when a settlement file is uploaded from a PSP. The service matches each PSP transaction row against a payment intent and flags rows that don't match as exceptions.

Period locks are immutable

Once a period is locked (createPeriodLock), no new reconciliation runs can be created for that period. Unlock by deleting the lock — only operators with recon.period_lock.delete can do this.

Endpoint reference

Dashboard

KPI cards, trend graphs, and obligation tables for the recon console landing page.

GET/api/recon/v1/dashboard/kpis

Get reconciliation KPI summary

GET/api/recon/v1/dashboard/obligations

Get upcoming settlement obligations

GET/api/recon/v1/dashboard/top-merchants

Get top merchants by exposure

GET/api/recon/v1/dashboard/trend

Get reconciliation trend data

Merchants & MDR rates

Recon-side merchant registry and Merchant Discount Rate configuration. MDR changes are maker/checker governed — submit, then approve or reject.

GET/api/recon/v1/merchants

List merchants

GET/api/recon/v1/merchants/{id}

Get a merchant

GET/api/recon/v1/merchants/{id}/mdr-rate-changes

List staged MDR-rate changes for a merchant

GET/api/recon/v1/merchants/{id}/mdr-rates

List MDR rates for a merchant

GET/api/recon/v1/merchants/{id}/mdr-rates/active

Get the currently active MDR rate for a merchant

POST/api/recon/v1/merchants

Create a merchant

POST/api/recon/v1/merchants/{id}/mdr-rate-changes/{changeId}/approve

Approve a staged MDR-rate change (checker step)

POST/api/recon/v1/merchants/{id}/mdr-rate-changes/{changeId}/reject

Reject a staged MDR-rate change (checker step)

POST/api/recon/v1/merchants/{id}/mdr-rates

Submit a staged MDR-rate change (maker step)

POST/api/recon/v1/merchants/{id}/status

Set merchant status

PUT/api/recon/v1/merchants/{id}

Update a merchant

DELETE/api/recon/v1/merchants/{id}

Delete a merchant

Reconciliation runs

Upload PSP settlement files and track the matching pipeline.

GET/api/recon/v1/reconciliation/runs

List reconciliation runs

GET/api/recon/v1/reconciliation/runs/{id}

Get a reconciliation run

GET/api/recon/v1/reconciliation/runs/{id}/download

Download reconciliation run result as CSV

GET/api/recon/v1/reconciliation/runs/{id}/transactions

List transactions for a reconciliation run

GET/api/recon/v1/reports/reconciliation/{runID}/csv

Download reconciliation report for a run as CSV

POST/api/recon/v1/reconciliation/upload

Upload internal and external files to start a reconciliation run

Transactions

Query individual payment transactions and list paginated transaction records.

GET/api/recon/v1/transactions

List transactions

GET/api/recon/v1/transactions/{id}

Get a transaction

Exceptions

Rows from PSP files that couldn't be automatically matched. Must be resolved before disbursement.

GET/api/recon/v1/exceptions

List exceptions

GET/api/recon/v1/exceptions/{id}

Get an exception

GET/api/recon/v1/exceptions/{id}/match-candidates

Get candidate transactions for manual match

GET/api/recon/v1/exceptions/{id}/notes

List notes on an exception

GET/api/recon/v1/exceptions/stats

Get exception statistics

GET/api/recon/v1/reports/exceptions

Download exceptions report as CSV

POST/api/recon/v1/exceptions/{id}/assign

Assign an exception to a user

POST/api/recon/v1/exceptions/{id}/escalate

Escalate an exception

POST/api/recon/v1/exceptions/{id}/manual-match

Manually match an exception to a transaction

POST/api/recon/v1/exceptions/{id}/notes

Add a note to an exception

POST/api/recon/v1/exceptions/{id}/resolve

Resolve an exception

POST/api/recon/v1/exceptions/bulk-update

Bulk update exception statuses

POST/api/recon/v1/exceptions/refresh-aging

Refresh aging days for open exceptions

Settlements

Manage and update settlement records and SLA status.

GET/api/recon/v1/settlements

List settlements

GET/api/recon/v1/settlements/{id}

Get a settlement

POST/api/recon/v1/settlements/bulk-update

Bulk update settlement statuses

POST/api/recon/v1/settlements/refresh-sla

Refresh SLA status for all settlements

PUT/api/recon/v1/settlements/{id}/status

Update settlement status

PUT/api/recon/v1/settlements/reorder

Reorder settlement priority

Disbursements

Multi-step approval workflow — submit → ops approve → CFO approve → mark paid.

GET/api/recon/v1/disbursement-batches

List disbursement batches

GET/api/recon/v1/disbursement-batches/{id}

Get a disbursement batch

GET/api/recon/v1/disbursement-batches/{id}/items

List items in a disbursement batch

GET/api/recon/v1/disbursements/{id}/report

Download disbursement batch report (CSV; PDF returns 501)

POST/api/recon/v1/disbursement-batches/{id}/approve

Approve a disbursement batch

POST/api/recon/v1/disbursement-batches/{id}/cfo-approve

CFO approval for a disbursement batch

POST/api/recon/v1/disbursement-batches/{id}/cfo-reject

CFO rejection for a disbursement batch

POST/api/recon/v1/disbursement-batches/{id}/mark-paid

Mark a disbursement batch as paid

POST/api/recon/v1/disbursement-batches/{id}/reject

Reject a disbursement batch

POST/api/recon/v1/disbursement-batches/{id}/submit

Submit a disbursement batch for approval

Deductions

PSP-side deductions (MDR, interchange, penalties) that reduce settlement amounts.

GET/api/recon/v1/deductions

List deductions

GET/api/recon/v1/deductions/{id}

Get a deduction

GET/api/recon/v1/reports/deductions-summary

Download deductions summary report as CSV

POST/api/recon/v1/deductions/{id}/flag-dispute

Flag a deduction for dispute

POST/api/recon/v1/deductions/{id}/recon-status

Set deduction reconciliation status

POST/api/recon/v1/deductions/{id}/resolve

Resolve a deduction dispute

POST/api/recon/v1/deductions/upload

Upload deductions from a CSV/Excel file

Risk holds

Funds held pending investigation — fraud review, compliance, or SLA breach.

GET/api/recon/v1/reports/risk-holds

Download risk holds report as CSV

GET/api/recon/v1/risk-holds

List risk holds

GET/api/recon/v1/risk-holds/{id}

Get a risk hold

POST/api/recon/v1/risk-holds/{id}/release

Release a risk hold

POST/api/recon/v1/risk-holds/{id}/status

Set risk hold status

POST/api/recon/v1/risk-holds/upload

Upload risk holds from a CSV/Excel file

Period locks

Freeze a calendar period so no new runs can be started against it.

GET/api/recon/v1/reconciliation-period-locks

List reconciliation period locks

POST/api/recon/v1/reconciliation-period-locks

Lock a reconciliation period

DELETE/api/recon/v1/reconciliation-period-locks/{id}

Unlock a reconciliation period

Integrations

Connect PSP file-delivery channels (SFTP, S3, API pull) and validate field mappings.

GET/api/recon/v1/integrations

List integrations

GET/api/recon/v1/integrations/{id}

Get an integration

GET/api/recon/v1/integrations/canonical-fields

Get canonical field definitions for mapping

POST/api/recon/v1/integrations

Create an integration

POST/api/recon/v1/integrations/{id}/status

Set integration status

POST/api/recon/v1/integrations/validate-mapping

Validate a column mapping against canonical fields

PUT/api/recon/v1/integrations/{id}

Update an integration

DELETE/api/recon/v1/integrations/{id}

Delete an integration

Rules engine

Configurable matching rules that automate exception classification.

GET/api/recon/v1/rules

List rules

GET/api/recon/v1/rules/{id}

Get a rule

GET/api/recon/v1/rules/types

List available rule types

POST/api/recon/v1/rules

Create a rule

PUT/api/recon/v1/rules/{id}

Update a rule

DELETE/api/recon/v1/rules/{id}

Delete a rule

Reports & schedules

Monthly reports, scheduled export jobs, and report download.

GET/api/recon/v1/report-schedules

List report schedules

GET/api/recon/v1/report-schedules/{id}

Get a report schedule

GET/api/recon/v1/reports/monthly

Get monthly reconciliation report

POST/api/recon/v1/report-schedules

Create a report schedule

POST/api/recon/v1/report-schedules/{id}/enabled

Enable or disable a report schedule

PUT/api/recon/v1/report-schedules/{id}

Update a report schedule

DELETE/api/recon/v1/report-schedules/{id}

Delete a report schedule

Notifications

In-app notifications, read-state management, and delivery channel configuration.

GET/api/recon/v1/me/notification-preferences

List notification preferences for the current user

GET/api/recon/v1/me/notification-preferences/{event_type}

Get notification preference for an event type

GET/api/recon/v1/notification-channels

List notification channels

GET/api/recon/v1/notification-channels/{id}

Get a notification channel

GET/api/recon/v1/notifications

List notifications for the current user

GET/api/recon/v1/notifications/unread-count

Get unread notification count for the current user

POST/api/recon/v1/notification-channels

Create a notification channel

POST/api/recon/v1/notification-channels/{id}/enabled

Enable or disable a notification channel

POST/api/recon/v1/notifications/{id}/read

Mark a notification as read

POST/api/recon/v1/notifications/read-all

Mark all notifications as read for the current user

PUT/api/recon/v1/me/notification-preferences/{event_type}

Create or update notification preference for an event type

PUT/api/recon/v1/notification-channels/{id}

Update a notification channel

DELETE/api/recon/v1/me/notification-preferences/{event_type}

Delete notification preference for an event type

DELETE/api/recon/v1/notification-channels/{id}

Delete a notification channel

Audit trail

Immutable audit log of all operator actions.

GET/api/recon/v1/audit-trail

List audit trail entries

GET/api/recon/v1/audit-trail/export

Export audit trail as CSV

Settings & webhooks

Global recon settings and back-office webhook configuration.

GET/api/recon/v1/bo-webhook-settings

Get back-office webhook settings

GET/api/recon/v1/settings

List all settings

GET/api/recon/v1/settings/{key}

Get a setting by key

PUT/api/recon/v1/bo-webhook-settings

Create or update back-office webhook settings

PUT/api/recon/v1/settings/{key}

Create or update a setting

DELETE/api/recon/v1/settings/{key}

Delete a setting

Files & utilities

Upload files for format auto-detection and mapping validation.

POST/api/recon/v1/files/upload

Upload a file and detect its format

Ungrouped operations

50 operations in the spec are not listed in the groups file. Add their operationIds to content/docs/api/recon.groups.json.

GET/api/recon/v1/ar-deductions/batches

List monthly AR deduction batches

GET/api/recon/v1/ar-deductions/batches/{id}

Get an AR batch with its staged lines

GET/api/recon/v1/ar-deductions/layout

Get the tenant's AR pivot layout

GET/api/recon/v1/bo/transactions/lookup

Look up transactions directly against the Back-Office API

GET/api/recon/v1/dashboard/action-summary

Get the caller's outstanding action summary

GET/api/recon/v1/deduction-schemes

List a merchant's deduction schemes

GET/api/recon/v1/deduction-schemes/{id}

Get a deduction scheme

GET/api/recon/v1/disbursement-cfo-threshold

Read the tenant's CFO approval threshold for disbursement batches

GET/api/recon/v1/integrations/{id}/revisions

List a provider profile's revision history

GET/api/recon/v1/merchants/options

List merchants for a picker

GET/api/recon/v1/rails

List the tenant's disbursement rail configurations

GET/api/recon/v1/refund-requests

List refund requests

GET/api/recon/v1/refund-requests/{id}

Get a refund request

GET/api/recon/v1/settlement-sources

List the tenant's settlement sources

GET/api/recon/v1/settlement-sources/routing

List settlement sources — routing projection

GET/api/recon/v1/source-config

Get the tenant's source-adapter mode selector

GET/api/recon/v1/source-config/field-mapping

Get the tenant's Back-Office field mapping

GET/api/recon/v1/source-config/mode

Get the workspace's ingest shape (mode only)

POST/api/recon/v1/ar-deductions/batches/{id}/approve

Approve a monthly AR deduction batch (Ops checker)

POST/api/recon/v1/ar-deductions/batches/{id}/reject

Reject a monthly AR deduction batch (Ops checker)

POST/api/recon/v1/ar-deductions/preview

Dry-run an AR file against a layout

POST/api/recon/v1/ar-deductions/upload

Upload a monthly per-MRC AR deduction file

POST/api/recon/v1/deduction-schemes

Submit a deduction scheme (Sales-Support maker)

POST/api/recon/v1/deduction-schemes/{id}/approve

Approve a deduction scheme (checker)

POST/api/recon/v1/deduction-schemes/{id}/reject

Reject a deduction scheme (checker)

POST/api/recon/v1/disbursement-batches

Create a disbursement batch from a completed reconciliation run

POST/api/recon/v1/disbursement-batches/{id}/execute

Execute (push) an approved disbursement batch to the bank rail

POST/api/recon/v1/disbursement-batches/{id}/sync-status

Sync a processing disbursement batch's status from the rail

POST/api/recon/v1/integrations/{id}/reset-to-catalogue

Reset a provider profile to its shipped catalogue default

POST/api/recon/v1/integrations/preview

Preview a sample settlement/report file against a provider mapping

POST/api/recon/v1/refund-requests

Submit a refund request (Risk maker)

POST/api/recon/v1/refund-requests/{id}/approve

Approve a refund request (Ops checker)

POST/api/recon/v1/refund-requests/{id}/reject

Reject a refund request (Ops checker)

POST/api/recon/v1/refund-requests/{id}/request

Forward a refund request for checker approval (Ops maker)

POST/api/recon/v1/risk-holds

Hold a single transaction

POST/api/recon/v1/risk-holds/{id}/approve

Approve a pending risk hold

POST/api/recon/v1/risk-holds/{id}/reject

Reject a risk hold or a requested release

POST/api/recon/v1/risk-holds/{id}/request-release

Request release of an active risk hold

POST/api/recon/v1/settled-status/ingest

Ingest a BO settled-status file

POST/api/recon/v1/settlement-sources

Create a settlement source

POST/api/recon/v1/settlement/pull

Pull settlement files over SFTP for the tenant

POST/api/recon/v1/source-config/test-connection

Test the tenant's Back-Office connection

POST/api/recon/v1/transactions/pull

Pull the Back-Office transaction feed for a date window

PUT/api/recon/v1/ar-deductions/layout

Save the tenant's AR pivot layout

PUT/api/recon/v1/disbursement-cfo-threshold

Change the tenant's CFO approval threshold

PUT/api/recon/v1/rails/{rail}

Upsert one disbursement rail's configuration

PUT/api/recon/v1/settlement-sources/{id}

Update a settlement source

PUT/api/recon/v1/source-config

Upsert the tenant's source-adapter mode selector

PUT/api/recon/v1/source-config/field-mapping

Upsert the tenant's Back-Office field mapping

DELETE/api/recon/v1/settlement-sources/{id}

Disable a settlement source

Was this page helpful?