Reconcile a settlement

Upload a PSP settlement file, review exceptions, lock the period, submit disbursement

Execute curls interactively

To run these API calls directly from your browser, open the Recon API reference and use the built-in Try-it playground. Authenticate with your console JWT (Bearer token from the dashboard), pick Sandbox, and send without leaving the docs.

Settlement reconciliation matches PSP-reported transactions against 505pay intents, resolves discrepancies, and releases net for disbursement.

Who runs this: finance / back-office operators with recon.* permissions (JWT, not API key — this is a console flow).

Upload the PSP settlement file

A single multipart request creates the reconciliation run AND attaches the file:

curl -X POST https://sandbox.505pay.link/api/recon/v1/reconciliation/upload \
  -H "Authorization: Bearer $JWT" \
  -F "integration_id=018f4d9f-…" \
  -F "period=2026-05-11" \
  -F "file=@bca_settlement_2026-05-11.csv;type=text/csv"
# → { "run_id": "018f…", "status": "pending" }

integration_id is the PSP integration UUID (see GET /api/recon/v1/integrations). period is the calendar day the settlement covers.

Wait for processing

The run moves pending → processing → completed or completed_with_exceptions. Poll:

curl "https://sandbox.505pay.link/api/recon/v1/reconciliation/runs/$RUN_ID" \
  -H "Authorization: Bearer $JWT"
# → { "status": "completed_with_exceptions", "matched": 498, "exceptions": 3 }

Or subscribe to the back-office webhook (POST /api/recon/v1/bo-webhooks/settings) to receive a push on completion.

Resolve exceptions

# List
curl "https://sandbox.505pay.link/api/recon/v1/exceptions?run_id=$RUN_ID" \
  -H "Authorization: Bearer $JWT"

# Manually match an exception to a transaction
curl -X POST "https://sandbox.505pay.link/api/recon/v1/exceptions/$EX_ID/manual-match" \
  -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
  -d '{"transaction_id": "018f…"}'

# Or write it off
curl -X POST "https://sandbox.505pay.link/api/recon/v1/exceptions/$EX_ID/resolve" \
  -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
  -d '{"resolution": "write_off", "note": "PSP duplicate row confirmed with BCA ops"}'

Lock the period

curl -X POST https://sandbox.505pay.link/api/recon/v1/period-locks \
  -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
  -d '{"period": "2026-05-11"}'

Period locks are immutable

You cannot create new reconciliation runs for a locked period. Unlock requires recon.period_lock.delete permission.

Submit the disbursement batch

curl -X POST https://sandbox.505pay.link/api/recon/v1/disbursements \
  -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
  -d '{"settlement_ids": ["018f…"], "period": "2026-05-11"}'

Ops → CFO two-eyes approval. See Recon Service API for the approval endpoints.

Was this page helpful?