> ## 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. # Record a delivery attempt > Requires payment_observations:write and a partner receipt delivery owner. Records one immutable delivery attempt: an API delivery or file download, with the outcome downloaded, delivered or failed. An attempt is evidence of delivery only. It never marks the Payment accepted, never moves funds and never changes accountingAcceptance; only receipt lines acknowledged through a payment reconciliation do. Reusing the attempt identity with an identical body returns 200 and changes nothing, so a lost response is safe to repeat; different evidence returns 409. ## OpenAPI ````yaml /generated/inbound-api-v1.openapi.json put /v1/clients/{clientCode}/payment-deliveries/{externalPaymentRequestId}/attempts/{externalAttemptId} 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-deliveries/{externalPaymentRequestId}/attempts/{externalAttemptId}: put: tags: - Payment delivery summary: Record a delivery attempt description: >- Requires payment_observations:write and a partner receipt delivery owner. Records one immutable delivery attempt: an API delivery or file download, with the outcome downloaded, delivered or failed. An attempt is evidence of delivery only. It never marks the Payment accepted, never moves funds and never changes accountingAcceptance; only receipt lines acknowledged through a payment reconciliation do. Reusing the attempt identity with an identical body returns 200 and changes nothing, so a lost response is safe to repeat; different evidence returns 409. operationId: putPaymentDeliveryAttempt parameters: - description: >- Stable non-sensitive Client code authorized by the Integration grant. in: path name: clientCode required: true schema: $ref: '#/components/schemas/ExternalResourceId' - description: >- The hosted Payment request whose confirmed Payment is being delivered. in: path name: externalPaymentRequestId required: true schema: $ref: '#/components/schemas/ExternalResourceId' - description: >- Caller-assigned identifier of this delivery attempt. Reusing it with an identical body is a safe retry. in: path name: externalAttemptId required: true schema: $ref: '#/components/schemas/ExternalResourceId' requestBody: description: One uncompressed resource representation, limited to 256 KiB. content: application/json: example: channel: api outcome: delivered schema: $ref: '#/components/schemas/PaymentDeliveryAttempt' required: true responses: '200': content: application/json: example: accountingAcceptance: partially_acknowledged allocations: - allocatedAmount: amount: '100.00' currency: EUR allocationReference: 5f1d3c6e-2b6a-4a57-9a3e-0d8b1c2f4a10 externalReceivableId: REC_EXAMPLE_1 matchedAmount: amount: '100.00' currency: EUR unmatchedAmount: amount: '0.00' currency: EUR - allocatedAmount: amount: '200.00' currency: EUR allocationReference: 7a9e1b44-6c0f-4f25-8d71-3e5a9b0c6d21 externalReceivableId: REC_EXAMPLE_2 matchedAmount: amount: '0.00' currency: EUR unmatchedAmount: amount: '200.00' currency: EUR confirmedAt: '2026-10-15T12:00:00.000Z' delivery: attempts: - channel: api externalAttemptId: DELIVERY_ATTEMPT_1 outcome: delivered recordedAt: '2026-10-15T12:10:00.000Z' state: delivered deliveryOwner: partner externalPaymentRequestId: PAYREQ_EXAMPLE paymentAmount: amount: '300.00' currency: EUR paymentReference: 0c4e8a52-1d3b-4e6f-b7a9-2f5c8d1e3a60 reconciliations: - RECON_EXAMPLE unappliedAmount: amount: '0.00' currency: EUR unmatchedAmount: amount: '200.00' currency: EUR schema: $ref: '#/components/schemas/PaymentDeliveryResponse' 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: accountingAcceptance: partially_acknowledged allocations: - allocatedAmount: amount: '100.00' currency: EUR allocationReference: 5f1d3c6e-2b6a-4a57-9a3e-0d8b1c2f4a10 externalReceivableId: REC_EXAMPLE_1 matchedAmount: amount: '100.00' currency: EUR unmatchedAmount: amount: '0.00' currency: EUR - allocatedAmount: amount: '200.00' currency: EUR allocationReference: 7a9e1b44-6c0f-4f25-8d71-3e5a9b0c6d21 externalReceivableId: REC_EXAMPLE_2 matchedAmount: amount: '0.00' currency: EUR unmatchedAmount: amount: '200.00' currency: EUR confirmedAt: '2026-10-15T12:00:00.000Z' delivery: attempts: - channel: api externalAttemptId: DELIVERY_ATTEMPT_1 outcome: delivered recordedAt: '2026-10-15T12:10:00.000Z' state: delivered deliveryOwner: partner externalPaymentRequestId: PAYREQ_EXAMPLE paymentAmount: amount: '300.00' currency: EUR paymentReference: 0c4e8a52-1d3b-4e6f-b7a9-2f5c8d1e3a60 reconciliations: - RECON_EXAMPLE unappliedAmount: amount: '0.00' currency: EUR unmatchedAmount: amount: '200.00' currency: EUR schema: $ref: '#/components/schemas/PaymentDeliveryResponse' description: Delivery attempt recorded. 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 single provider-confirmed Payment to deliver. requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: >- The Payment request has no single provider-confirmed Payment to deliver. type: https://docs.paypathiq.com/problems/payment_not_confirmed financial_event_conflict: value: detail: The attempt identity already has different evidence. requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: The attempt identity already has different evidence. type: >- https://docs.paypathiq.com/problems/financial_event_conflict receipt_delivery_owner_mismatch: value: detail: >- This connection declares PayPathIQ as the receipt delivery owner, so partner retrieval, delivery and acknowledgement operations are unavailable. requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: >- This connection declares PayPathIQ as the receipt delivery owner, so partner retrieval, delivery and acknowledgement operations are unavailable. type: >- https://docs.paypathiq.com/problems/receipt_delivery_owner_mismatch schema: $ref: '#/components/schemas/Problem' description: >- The Payment request has no single provider-confirmed Payment to deliver. The attempt identity already has different evidence. This connection declares PayPathIQ as the receipt delivery owner, so partner retrieval, delivery and acknowledgement operations are unavailable. 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}$ PaymentDeliveryAttempt: type: object properties: channel: type: string enum: - api - file_download description: >- api: your middleware sent the Payment to the accounting system through its API. file_download: you exported it as a file for the accounting system. outcome: type: string enum: - downloaded - delivered - failed description: >- downloaded: you retrieved or exported the Payment details. delivered: the accounting system's intake received them. failed: the delivery did not complete. None of these is accounting acceptance: only receipt lines acknowledged through a payment reconciliation are. required: - channel - outcome additionalProperties: false PaymentDeliveryResponse: type: object properties: accountingAcceptance: type: string enum: - pending - partially_acknowledged - acknowledged - held description: >- pending: no receipt line has acknowledged this Payment. partially_acknowledged: some of the allocated amount is acknowledged. acknowledged: every allocated amount is acknowledged. held: a receipt line differs and affected actions are held. Derived only from payment reconciliations, never from delivery attempts or reads. 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 allocationReference: 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)$ description: A stable opaque reference to this allocation of the Payment. 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 - allocationReference - externalReceivableId - matchedAmount - unmatchedAmount additionalProperties: false confirmedAt: 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))$ delivery: type: object properties: attempts: type: array items: type: object properties: channel: type: string enum: - api - file_download externalAttemptId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ outcome: type: string enum: - downloaded - delivered - failed recordedAt: 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: - channel - externalAttemptId - outcome - recordedAt additionalProperties: false description: Delivery attempts you reported, oldest first. state: type: string enum: - not_attempted - downloaded - delivered - failed description: >- The outcome of the latest reported attempt, or not_attempted. Retrieving this resource never changes it. required: - attempts - state additionalProperties: false deliveryOwner: type: string const: partner description: >- The agreed owner of receipt delivery for this connection. Only the owner may retrieve, deliver and acknowledge. externalPaymentRequestId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ 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 paymentReference: 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)$ description: A stable opaque reference to the confirmed Payment. reconciliations: type: array items: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ description: >- Identifiers of the payment reconciliations that acknowledged this Payment. 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 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: - accountingAcceptance - allocations - confirmedAt - delivery - deliveryOwner - externalPaymentRequestId - paymentAmount - paymentReference - reconciliations - 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.