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.

GET/api/recon/v1/merchants

List merchants

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

Get 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}/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

19 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/merchants/{id}/mdr-rate-changes

List staged MDR-rate changes for a merchant

GET/api/recon/v1/refund-requests

List refund requests

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

Get a refund request

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/upload

Upload a monthly per-MRC AR deduction file

POST/api/recon/v1/disbursement-batches

Create a disbursement batch from a completed reconciliation run

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/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/{id}/approve

Approve a pending risk hold

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

Was this page helpful?