Skip to content
StraventaDocs
Now in Sandbox.
API Reference

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

EnvironmentHostname
Sandboxhttps://sandbox.505pay.link
Productionhttps://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.

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.

Transactions

Query individual payment transactions and list paginated transaction records.

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.

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.

Risk holds

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

Period locks

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

Integrations

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

Rules engine

Configurable matching rules that automate exception classification.

Reports & schedules

Monthly reports, scheduled export jobs, and report download.

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.

Settings & webhooks

Global recon settings and back-office webhook configuration.

Files & utilities

Upload files for format auto-detection and mapping validation.

Ungrouped operations

82 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/availability

Show which dates in a window have Back-Office data

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/dashboard/alerts

List the caller's active dashboard alerts

GET/api/recon/v1/dashboard/liquidity

Get the tenant's liquidity position

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}/catalogue-diff

Field-level difference between a provider profile and its catalogue default

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/rails/{rail}/balance

Read a rail's funding balance

GET/api/recon/v1/rails/{rail}/invoices

List billable-lookup invoices

GET/api/recon/v1/refund-requests

List refund requests

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

Get a refund request

GET/api/recon/v1/reports/dashboard-sheet

Download the client Dashboard sheet projection as CSV

GET/api/recon/v1/reports/dashboard-sheet/rows

One page of the client Dashboard sheet as JSON

GET/api/recon/v1/reports/disbursement-summary-by-mrc

Download the disbursement summary per MRC (with deductions) as CSV

GET/api/recon/v1/reports/failed-transfers

Download the Gagal Transfer (failed transfer) report as CSV

GET/api/recon/v1/reports/transactions-by-tid

Download the TID-keyed transaction report for one channel as CSV

GET/api/recon/v1/reports/transactions-by-tid/channels

Coverage matrix for the TID-keyed report

GET/api/recon/v1/settings/escalation-rules

List the effective escalation ladders

GET/api/recon/v1/settings/notification-policies

List the effective notification channel policy

GET/api/recon/v1/settings/thresholds

List effective notification and alert thresholds

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)

GET/api/recon/v1/tenant-data/reset-preview

Preview a reconciliation-data reset

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/dashboard/alerts/{id}/dismiss

Dismiss a dashboard alert for the caller

POST/api/recon/v1/dashboard/alerts/{id}/snooze

Snooze a dashboard alert for the caller

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 selected settlements

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

Discard a draft disbursement batch

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}/release-settlements

Release a dead batch's unpaid settlements

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/rails/{rail}/invoices/{invoice_ref}/pay

Pay one billable-lookup invoice

POST/api/recon/v1/rails/{rail}/invoices/sync

Refresh the invoice projection from the rail

POST/api/recon/v1/reconciliation-runs/{id}/dispute-refresh

Refresh a Dispute-Amount group from the Back Office and re-reconcile it

POST/api/recon/v1/reconciliation/compare

Stage a reconciliation drop and return its total-comparison verdict

POST/api/recon/v1/reconciliation/compare/{staged_drop_id}/run

Reconcile a previously staged drop

POST/api/recon/v1/reconciliation/detect

Detect how each file would be routed and parsed, without writing anything

POST/api/recon/v1/reconciliation/runs/{id}/rerun-by-txid

Re-reconcile a disputed per-MID group at transaction granularity

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/tenant-data/reset

Reset the tenant's reconciliation data

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/settings/escalation-rules

Set or reset escalation ladders

PUT/api/recon/v1/settings/notification-policies

Set or reset notification channel policies

PUT/api/recon/v1/settings/thresholds

Set or reset notification and alert thresholds

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/reconciliation/compare/{staged_drop_id}

Discard a staged reconciliation drop

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

Disable a settlement source

Was this page helpful?

Marketplace Service API

The per-tenant storefront sales channel — opening hours, catalogue browse, feature switches, shipping, promo codes, buyer accounts, wishlist, reviews, fulfilment and the storefront's legal documents

Disbursement Service API

Internal money-movement service — rail configuration, funding balance, billable-lookup invoices, and idempotent transfers

On this page

Base URLsReconciliation run lifecycleEndpoint reference