> ## Documentation Index > Fetch the complete documentation index at: https://docs.paypathiq.com/llms.txt > Use this file to discover all available pages before exploring further. # Reconcile a Payment against accounting receipt lines > Requires payment_observations:write. Acknowledges the confirmed Payment of a hosted Payment request against one or more Source receipt lines. A line matches only when its stable receipt identity, Client, currency and Receivable reference fit an allocation of that Payment and the line fits inside the allocated amount not yet acknowledged; similar amounts or dates never match. Several reconciliations may acknowledge one Payment progressively, and the unmatched remainder stays explicit. No reconciliation changes funds, balances or the Payment: replaying a receipt acknowledges existing funds without another deduction. A line that does not fit is stored as held, preserving both figures, and the affected Receivables have recovery and Payment actions held until matching evidence or an authorized correction resolves it; other Receivables continue. Reconciliation is accepted while the Source feed is stale. Reusing a receipt line identity with different evidence returns 409 and records nothing. An identical retry returns 200 and changes nothing. ## OpenAPI ````yaml /generated/inbound-api-v1.openapi.json put /v1/clients/{clientCode}/payment-reconciliations/{externalReconciliationId} openapi: 3.1.0 info: description: >- Send Customers, Receivables, and Payment observations and related financial evidence from your source system to PayPathIQ, one record at a time or as bounded asynchronous batches, and read back changes. Every operation listed here is implemented; capabilities that are not implemented are not listed. Start in sandbox with a sandbox key and synthetic data. Every error type links to a page at https://docs.paypathiq.com/problems/{code}. title: PayPathIQ Inbound Receivables API version: 1.0.0 servers: - description: Sandbox url: https://api.sandbox.paypathiq.com - description: Production url: https://api.paypathiq.com security: - BearerAuth: [] tags: - description: >- PayPathIQ-owned delivery of receipts to the accounting Source, with acknowledgement kept separate. name: Receipt delivery - description: People and businesses that owe one Client. name: Customers - description: Independently recoverable Receivables. name: Receivables - description: Immutable evidence of external payments, refunds, and reversals. name: Payment observations - description: >- Ordered Source balance snapshots for transaction and snapshot-only connections. name: Balance snapshots - description: >- Bounded asynchronous ingestion of up to 100 records with exact per-record outcomes. name: Batches - description: >- Verified complete-book declarations that flag and hold Receivables missing from the book. name: Complete books - description: Durable, resumable record of committed Customer and Receivable changes. name: Changes - description: >- Optional signed, minimal notifications that a Customer or Receivable changed. name: Webhooks - description: >- Fixed-amount hosted payment pages through the Client's own payment provider merchant. name: Payment requests - description: >- Partner-owned delivery of confirmed Payments to accounting, kept separate from accounting acceptance. name: Payment delivery - description: Explicit Receivable pause and closure commands. name: Receivable lifecycle - description: >- Explicit, revisioned instructions that let PayPathIQ begin recovery for a Receivable. name: Recovery instructions - description: >- Permissioned working collection position, holds, commitments and action outcomes, separate from the Source representation. name: Collection summaries - description: Whether accepted source evidence is recent enough to act on. name: Source freshness - description: This machine-readable API contract. name: Specification paths: /v1/clients/{clientCode}/payment-reconciliations/{externalReconciliationId}: put: tags: - Payment reconciliation summary: Reconcile a Payment against accounting receipt lines description: >- Requires payment_observations:write. Acknowledges the confirmed Payment of a hosted Payment request against one or more Source receipt lines. A line matches only when its stable receipt identity, Client, currency and Receivable reference fit an allocation of that Payment and the line fits inside the allocated amount not yet acknowledged; similar amounts or dates never match. Several reconciliations may acknowledge one Payment progressively, and the unmatched remainder stays explicit. No reconciliation changes funds, balances or the Payment: replaying a receipt acknowledges existing funds without another deduction. A line that does not fit is stored as held, preserving both figures, and the affected Receivables have recovery and Payment actions held until matching evidence or an authorized correction resolves it; other Receivables continue. Reconciliation is accepted while the Source feed is stale. Reusing a receipt line identity with different evidence returns 409 and records nothing. An identical retry returns 200 and changes nothing. operationId: putPaymentReconciliation parameters: - description: >- Stable non-sensitive Client code authorized by the Integration grant. in: path name: clientCode required: true schema: $ref: '#/components/schemas/ExternalResourceId' - description: >- Caller-assigned identifier of this reconciliation. Reusing it with an identical body is a safe retry. in: path name: externalReconciliationId required: true schema: $ref: '#/components/schemas/ExternalResourceId' requestBody: description: One uncompressed resource representation, limited to 256 KiB. content: application/json: example: externalPaymentRequestId: PAYREQ_EXAMPLE receiptLines: - amount: amount: '100.00' currency: EUR externalReceiptLineId: RCPT_LINE_1 externalReceivableId: REC_EXAMPLE_1 schema: $ref: '#/components/schemas/PaymentReconciliation' required: true responses: '200': content: application/json: example: acceptedAt: '2026-10-15T12:30:00.000Z' allocations: - allocatedAmount: amount: '100.00' currency: EUR externalReceivableId: REC_EXAMPLE_1 matchedAmount: amount: '100.00' currency: EUR unmatchedAmount: amount: '0.00' currency: EUR - allocatedAmount: amount: '200.00' currency: EUR externalReceivableId: REC_EXAMPLE_2 matchedAmount: amount: '0.00' currency: EUR unmatchedAmount: amount: '200.00' currency: EUR externalPaymentRequestId: PAYREQ_EXAMPLE externalReconciliationId: RECON_EXAMPLE lines: - amount: amount: '100.00' currency: EUR externalReceiptLineId: RCPT_LINE_1 externalReceivableId: REC_EXAMPLE_1 state: matched paymentAmount: amount: '300.00' currency: EUR revision: 1 status: matched unappliedAmount: amount: '0.00' currency: EUR unmatchedAmount: amount: '200.00' currency: EUR schema: $ref: '#/components/schemas/PaymentReconciliationResponse' description: Identical safe retry. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '201': content: application/json: example: acceptedAt: '2026-10-15T12:30:00.000Z' allocations: - allocatedAmount: amount: '100.00' currency: EUR externalReceivableId: REC_EXAMPLE_1 matchedAmount: amount: '100.00' currency: EUR unmatchedAmount: amount: '0.00' currency: EUR - allocatedAmount: amount: '200.00' currency: EUR externalReceivableId: REC_EXAMPLE_2 matchedAmount: amount: '0.00' currency: EUR unmatchedAmount: amount: '200.00' currency: EUR externalPaymentRequestId: PAYREQ_EXAMPLE externalReconciliationId: RECON_EXAMPLE lines: - amount: amount: '100.00' currency: EUR externalReceiptLineId: RCPT_LINE_1 externalReceivableId: REC_EXAMPLE_1 state: matched paymentAmount: amount: '300.00' currency: EUR revision: 1 status: matched unappliedAmount: amount: '0.00' currency: EUR unmatchedAmount: amount: '200.00' currency: EUR schema: $ref: '#/components/schemas/PaymentReconciliationResponse' description: Receipt lines recorded atomically. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string Location: description: Canonical URL of the created Integration-facing resource. schema: type: string format: uri '400': content: application/problem+json: examples: malformed_json: value: detail: Request body is not valid JSON. requestId: 29400000-0000-4000-8000-000000000001 status: 400 title: Request body is not valid JSON. type: https://docs.paypathiq.com/problems/malformed_json schema: $ref: '#/components/schemas/Problem' description: Request body is not valid JSON. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '401': content: application/problem+json: examples: invalid_api_key: value: detail: >- API key is invalid, inactive, revoked, or for another environment. requestId: 29400000-0000-4000-8000-000000000001 status: 401 title: >- API key is invalid, inactive, revoked, or for another environment. type: https://docs.paypathiq.com/problems/invalid_api_key schema: $ref: '#/components/schemas/Problem' description: API key is invalid, inactive, revoked, or for another environment. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '403': content: application/problem+json: examples: client_scope_denied: value: detail: >- The Client code is unknown, the grant lacks the required scope, or the calling address is outside the grant's IP allowlist. requestId: 29400000-0000-4000-8000-000000000001 status: 403 title: >- The Client code is unknown, the grant lacks the required scope, or the calling address is outside the grant's IP allowlist. type: https://docs.paypathiq.com/problems/client_scope_denied schema: $ref: '#/components/schemas/Problem' description: >- The Client code is unknown, the grant lacks the required scope, or the calling address is outside the grant's IP allowlist. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '404': content: application/problem+json: examples: payment_request_not_found: value: detail: No Payment request exists at this authorized reference. requestId: 29400000-0000-4000-8000-000000000001 status: 404 title: No Payment request exists at this authorized reference. type: >- https://docs.paypathiq.com/problems/payment_request_not_found schema: $ref: '#/components/schemas/Problem' description: No Payment request exists at this authorized reference. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '409': content: application/problem+json: examples: payment_not_confirmed: value: detail: >- The Payment request has no provider-confirmed Payment to acknowledge. requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: >- The Payment request has no provider-confirmed Payment to acknowledge. type: https://docs.paypathiq.com/problems/payment_not_confirmed financial_event_conflict: value: detail: >- A reconciliation or receipt line identity already has different immutable evidence. requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: >- A reconciliation or receipt line identity already has different immutable evidence. type: >- https://docs.paypathiq.com/problems/financial_event_conflict schema: $ref: '#/components/schemas/Problem' description: >- The Payment request has no provider-confirmed Payment to acknowledge. A reconciliation or receipt line identity already has different immutable evidence. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '413': content: application/problem+json: examples: request_too_large: value: detail: Request body exceeds the 256 KiB resource limit. requestId: 29400000-0000-4000-8000-000000000001 status: 413 title: Request body exceeds the 256 KiB resource limit. type: https://docs.paypathiq.com/problems/request_too_large schema: $ref: '#/components/schemas/Problem' description: Request body exceeds the 256 KiB resource limit. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '415': content: application/problem+json: examples: unsupported_media_type: value: detail: >- Media type or content encoding is unsupported. Send uncompressed application/json for PUT and POST, and application/merge-patch+json for PATCH. requestId: 29400000-0000-4000-8000-000000000001 status: 415 title: >- Media type or content encoding is unsupported. Send uncompressed application/json for PUT and POST, and application/merge-patch+json for PATCH. type: https://docs.paypathiq.com/problems/unsupported_media_type schema: $ref: '#/components/schemas/Problem' description: >- Media type or content encoding is unsupported. Send uncompressed application/json for PUT and POST, and application/merge-patch+json for PATCH. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '422': content: application/problem+json: examples: validation_error: value: detail: >- Route parameters or the representation are invalid. Route parameters are checked before authentication. Field errors carry a code such as invalid_format, unrecognized_keys, custom, sensitive_external_id, or sensitive_source_reference. errors: - code: invalid_format detail: Invalid ISO date pointer: /dueDate requestId: 29400000-0000-4000-8000-000000000001 status: 422 title: >- Route parameters or the representation are invalid. Route parameters are checked before authentication. Field errors carry a code such as invalid_format, unrecognized_keys, custom, sensitive_external_id, or sensitive_source_reference. type: https://docs.paypathiq.com/problems/validation_error schema: $ref: '#/components/schemas/Problem' description: >- Route parameters or the representation are invalid. Route parameters are checked before authentication. Field errors carry a code such as invalid_format, unrecognized_keys, custom, sensitive_external_id, or sensitive_source_reference. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '429': content: application/problem+json: examples: rate_limit_exceeded: value: detail: >- Each API key may send 60 requests per minute and run 1 request at a time. In sandbox, the same limits also apply per Client across all of its keys. Every request, including GET, counts. requestId: 29400000-0000-4000-8000-000000000001 status: 429 title: >- Each API key may send 60 requests per minute and run 1 request at a time. In sandbox, the same limits also apply per Client across all of its keys. Every request, including GET, counts. type: https://docs.paypathiq.com/problems/rate_limit_exceeded schema: $ref: '#/components/schemas/Problem' description: >- Each API key may send 60 requests per minute and run 1 request at a time. In sandbox, the same limits also apply per Client across all of its keys. Every request, including GET, counts. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string Retry-After: description: >- Seconds until this unchanged request may be retried: 1 after a concurrency rejection, 60 after the per-minute limit. schema: minimum: 1 type: integer '503': content: application/problem+json: examples: projection_unavailable: value: detail: >- An unexpected error prevented a safe commit, and nothing was saved. Retry with backoff. requestId: 29400000-0000-4000-8000-000000000001 status: 503 title: >- An unexpected error prevented a safe commit, and nothing was saved. Retry with backoff. type: https://docs.paypathiq.com/problems/projection_unavailable schema: $ref: '#/components/schemas/Problem' description: >- An unexpected error prevented a safe commit, and nothing was saved. Retry with backoff. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string security: - BearerAuth: [] components: schemas: ExternalResourceId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ PaymentReconciliation: type: object properties: externalPaymentRequestId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ description: >- The hosted Payment request whose confirmed Payment these receipt lines acknowledge. Matching uses this stable reference, the Client, the currency and the exact allocated amounts, never a similar amount or date. receiptLines: minItems: 1 maxItems: 50 type: array items: type: object properties: amount: type: object properties: amount: type: string pattern: ^(0|[1-9]\d{0,13})\.\d{2}$ currency: type: string const: EUR required: - amount - currency additionalProperties: false description: >- The exact amount the Source posted against this Receivable for this receipt line. externalReceiptLineId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ description: >- The Source's stable identity of this receipt line. It is unique across the connection and can never be reused for different evidence. externalReceivableId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ required: - amount - externalReceiptLineId - externalReceivableId additionalProperties: false description: >- One or more Source receipt lines. A Payment may be acknowledged progressively across several reconciliations. required: - externalPaymentRequestId - receiptLines additionalProperties: false PaymentReconciliationResponse: type: object properties: acceptedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ allocations: type: array items: type: object properties: allocatedAmount: type: object properties: amount: type: string pattern: ^(0|[1-9]\d{0,13})\.\d{2}$ currency: type: string const: EUR required: - amount - currency additionalProperties: false externalReceivableId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ matchedAmount: type: object properties: amount: type: string pattern: ^(0|[1-9]\d{0,13})\.\d{2}$ currency: type: string const: EUR required: - amount - currency additionalProperties: false unmatchedAmount: type: object properties: amount: type: string pattern: ^(0|[1-9]\d{0,13})\.\d{2}$ currency: type: string const: EUR required: - amount - currency additionalProperties: false required: - allocatedAmount - externalReceivableId - matchedAmount - unmatchedAmount additionalProperties: false description: >- The Payment's allocations as of this read, across every reconciliation of the Payment. unmatchedAmount is the allocated amount no Source receipt line has acknowledged yet. externalPaymentRequestId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ externalReconciliationId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ lines: type: array items: type: object properties: amount: type: object properties: amount: type: string pattern: ^(0|[1-9]\d{0,13})\.\d{2}$ currency: type: string const: EUR required: - amount - currency additionalProperties: false externalReceiptLineId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ externalReceivableId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ state: type: string enum: - matched - held - explained description: >- matched: counted against the allocated amount. held: the line does not fit the allocated amount, so it is not counted and affected actions are held. explained: a held line cleared by matching evidence or an authorized correction; its amount is still preserved and never counted. required: - amount - externalReceiptLineId - externalReceivableId - state additionalProperties: false paymentAmount: type: object properties: amount: type: string pattern: ^(0|[1-9]\d{0,13})\.\d{2}$ currency: type: string const: EUR required: - amount - currency additionalProperties: false resolution: type: object properties: basis: type: string enum: - matching_evidence - authorized_correction reference: type: string minLength: 1 maxLength: 200 resolvedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$ required: - basis - reference - resolvedAt additionalProperties: false revision: type: integer minimum: 1 maximum: 9007199254740991 description: >- Increases each time the reconciliation's state changes. It matches the revision in change-feed events. status: type: string enum: - matched - held - resolved description: >- matched: every line fits the allocated amounts. held: at least one line differs and affected recovery and Payment actions are held. resolved: every difference was cleared by matching evidence or an authorized correction. unappliedAmount: type: object properties: amount: type: string pattern: ^(0|[1-9]\d{0,13})\.\d{2}$ currency: type: string const: EUR required: - amount - currency additionalProperties: false description: >- Funds of the Payment that no allocation covers. They are never acknowledged by receipt lines. unmatchedAmount: type: object properties: amount: type: string pattern: ^(0|[1-9]\d{0,13})\.\d{2}$ currency: type: string const: EUR required: - amount - currency additionalProperties: false description: >- The total allocated amount of the Payment that no Source receipt line has acknowledged yet. required: - acceptedAt - allocations - externalPaymentRequestId - externalReconciliationId - lines - paymentAmount - revision - status - unappliedAmount - unmatchedAmount additionalProperties: false Problem: type: object properties: detail: type: string errors: maxItems: 20 type: array items: type: object properties: code: type: string detail: type: string pointer: type: string required: - code - detail - pointer additionalProperties: false requestId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ status: type: integer minimum: 400 maximum: 599 title: type: string type: type: string format: uri required: - detail - requestId - status - title - type additionalProperties: false securitySchemes: BearerAuth: bearerFormat: ppiq_test__ or ppiq_live__ description: >- Integration-owned environment-specific API key. Never paste a production key into documentation tools. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.