Reconciliation

Reconciliation answers one question about a payment intent: did the funds that arrived match what was expected, and if an auto-swap ran, what did it cost? SouthPay writes a snapshot each time it checks. This endpoint returns the most recent one. Use it when a payment settled for an amount you did not expect, or when closing your books against the reports export. Paths are relative to https://api.southpay.io/api/v2.

Get the reconciliation snapshot

GET /payment_intents/{payment_intent_id}/reconciliation. Scope payments:read.

This is the only payment route that uses the payment_intents path segment. Every other payment route uses payments. The reconciliation_status field on a payment intent is a shortcut to the status returned here.

curl https://api.southpay.io/api/v2/payment_intents/7b1f0c2e-2b0a-4c31-9f0e-1d2c3b4a5e6f/reconciliation \
  -H "Authorization: Bearer sp_sk_test_…"

{
  "status": "final",
  "expected_amount": "49.99",
  "received_amount": "49.99",
  "swap_delta": "0",
  "currency": "USDC",
  "expected_amount_atomic": "49990000",
  "received_amount_atomic": "49990000",
  "swap_delta_atomic": "0",
  "last_checked_at": "2026-05-12T12:05:00.000Z"
}

Response fields

string

required

One of final, under_investigation, disputed, closed. See statuses.

string | null

What the intent asked for, as a decimal string with trailing zeros stripped.

string | null

What actually arrived, as a decimal string.

string | null

Difference introduced by an auto-swap. Can be negative, for example "-0.001".

string | null

The coin symbol of the asset that was paid, such as USDC. This is not a fiat currency, despite the field name.

string

required

Atomic units. "0" when no snapshot exists.

string

required

Atomic units.

string

required

Atomic units, signed.

string | null

ISO 8601 timestamp of the snapshot. Null when none exists.

Before the first check

An intent that has never been reconciled, because it is unpaid or because the checker has not run yet, still returns 200, not 404. You get a placeholder:

Response 200

{
  "status": "under_investigation",
  "expected_amount": null,
  "received_amount": null,
  "swap_delta": null,
  "currency": "USDC",
  "expected_amount_atomic": "0",
  "received_amount_atomic": "0",
  "swap_delta_atomic": "0",
  "last_checked_at": null
}

Treat last_checked_at: null as “not yet checked”, not as a discrepancy. currency is still filled in from the intent’s deposit address when one exists.

Statuses

Status	Meaning
`final`	Checked and balanced. Nothing further to do.
`under_investigation`	A check is in progress, or no snapshot has been written yet.
`disputed`	A discrepancy was found and is being worked.
`closed`	The discrepancy was resolved and the snapshot was filed.

Errors

Status	Body	Cause
`403`	`{"error": {"message": "Insufficient scope: payments:read required", "code": "insufficient_scope"}}`	Credential lacks `payments:read`.
`404`	`{"error": "Payment intent not found"}`	Unknown id, or the intent belongs to the other mode.

Note the 404 here uses the flat string envelope, unlike most 404 responses in the API, which use {"error": {"message": …, "code": …}}.

Payments

Balances

Payouts

Billing

Webhooks

Platform

Agentic

Reports

Get the reconciliation snapshot

Response fields

Before the first check

Statuses

Errors

​Get the reconciliation snapshot

​Response fields

​Before the first check

​Statuses

​Errors

Get the reconciliation snapshot

Response fields

Before the first check

Statuses

Errors