> ## 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 Payment observation > Contract preview: Public API hostnames are not live yet; this operation is not currently runnable. Records immutable external evidence and the resulting Recoverable amount in one locked transaction. ## OpenAPI ````yaml /generated/inbound-api-v1.openapi.json put /v1/clients/{clientCode}/payment-observations/{externalPaymentObservationId} openapi: 3.1.0 info: description: >- Contract-first definition for record-level receivables ingestion. Routes become publicly available only after their implementation and transactional projection tests ship. 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: People and organisations responsible for payment. name: Parties - description: Independently recoverable obligations. name: Receivables - description: Immutable evidence of external payments, refunds, and reversals. name: Payment observations - description: Explicit Receivable pause and closure commands. name: Receivable lifecycle paths: /v1/clients/{clientCode}/payment-observations/{externalPaymentObservationId}: put: tags: - Payment observations summary: Record a Payment observation description: >- Contract preview: Public API hostnames are not live yet; this operation is not currently runnable. Records immutable external evidence and the resulting Recoverable amount in one locked transaction. operationId: putPaymentObservation parameters: - description: >- Stable non-sensitive Client code authorized by the Integration grant. in: path name: clientCode required: true schema: $ref: '#/components/schemas/ExternalResourceId' - description: >- Opaque immutable Payment-observation identifier supplied by the Integration. in: path name: externalPaymentObservationId required: true schema: $ref: '#/components/schemas/ExternalResourceId' requestBody: content: application/json: example: amount: amount: '250.00' currency: EUR effectiveAt: '2026-08-29T11:45:00Z' externalReceivableId: REC_123 method: bank_transfer resultingRecoverableAmount: amount: '1000.00' currency: EUR sourceReference: payment-ref-example type: payment schema: $ref: '#/components/schemas/PaymentObservation' description: 'Maximum uncompressed request body size: 256 KiB.' required: true responses: '200': content: application/json: example: amount: amount: '250.00' currency: EUR effectiveAt: '2026-08-29T11:45:00Z' externalReceivableId: REC_123 method: bank_transfer resultingRecoverableAmount: amount: '1000.00' currency: EUR sourceReference: payment-ref-example type: payment acceptedAt: '2026-08-29T12:00:00Z' externalPaymentObservationId: PAY_123 schema: $ref: '#/components/schemas/PaymentObservationResponse' description: Identical retry of the accepted observation. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Profile: description: Industry profile fixed by the current Integration grant. schema: const: credit_union.v1 type: string X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '201': content: application/json: example: amount: amount: '250.00' currency: EUR effectiveAt: '2026-08-29T11:45:00Z' externalReceivableId: REC_123 method: bank_transfer resultingRecoverableAmount: amount: '1000.00' currency: EUR sourceReference: payment-ref-example type: payment acceptedAt: '2026-08-29T12:00:00Z' externalPaymentObservationId: PAY_123 schema: $ref: '#/components/schemas/PaymentObservationResponse' description: Payment observation accepted and projected synchronously. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Profile: description: Industry profile fixed by the current Integration grant. schema: const: credit_union.v1 type: string 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. errors: - code: malformed_json detail: Request body is not valid JSON. pointer: / 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-Profile: description: Industry profile fixed by the current Integration grant. schema: const: credit_union.v1 type: string 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. errors: - code: invalid_api_key detail: >- API key is invalid, inactive, revoked, or for another environment. pointer: / 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-Profile: description: Industry profile fixed by the current Integration grant. schema: const: credit_union.v1 type: string 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: Client or Integration grant scope is denied. errors: - code: client_scope_denied detail: Client or Integration grant scope is denied. pointer: / requestId: 29400000-0000-4000-8000-000000000001 status: 403 title: Client or Integration grant scope is denied. type: https://docs.paypathiq.com/problems/client_scope_denied schema: $ref: '#/components/schemas/Problem' description: Client or Integration grant scope is denied. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Profile: description: Industry profile fixed by the current Integration grant. schema: const: credit_union.v1 type: string X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '409': content: application/problem+json: examples: balance_mismatch: value: detail: >- Resulting Recoverable amount does not match the locked Receivable balance. errors: - code: balance_mismatch detail: >- Resulting Recoverable amount does not match the locked Receivable balance. pointer: / requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: >- Resulting Recoverable amount does not match the locked Receivable balance. type: https://docs.paypathiq.com/problems/balance_mismatch dependency_missing: value: detail: >- Referenced Receivable or related Payment observation is missing. errors: - code: dependency_missing detail: >- Referenced Receivable or related Payment observation is missing. pointer: / requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: >- Referenced Receivable or related Payment observation is missing. type: https://docs.paypathiq.com/problems/dependency_missing payment_observation_conflict: value: detail: >- This external Payment ID already has different immutable content. errors: - code: payment_observation_conflict detail: >- This external Payment ID already has different immutable content. pointer: / requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: >- This external Payment ID already has different immutable content. type: >- https://docs.paypathiq.com/problems/payment_observation_conflict schema: $ref: '#/components/schemas/Problem' description: >- Resulting Recoverable amount does not match the locked Receivable balance. Referenced Receivable or related Payment observation is missing. This external Payment ID already has different immutable content. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Profile: description: Industry profile fixed by the current Integration grant. schema: const: credit_union.v1 type: string 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 limit. errors: - code: request_too_large detail: Request body exceeds the 256 KiB limit. pointer: / requestId: 29400000-0000-4000-8000-000000000001 status: 413 title: Request body exceeds the 256 KiB limit. type: https://docs.paypathiq.com/problems/request_too_large schema: $ref: '#/components/schemas/Problem' description: Request body exceeds the 256 KiB limit. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Profile: description: Industry profile fixed by the current Integration grant. schema: const: credit_union.v1 type: string 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. errors: - code: unsupported_media_type detail: Media type or content encoding is unsupported. pointer: / requestId: 29400000-0000-4000-8000-000000000001 status: 415 title: Media type or content encoding is unsupported. type: https://docs.paypathiq.com/problems/unsupported_media_type schema: $ref: '#/components/schemas/Problem' description: Media type or content encoding is unsupported. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Profile: description: Industry profile fixed by the current Integration grant. schema: const: credit_union.v1 type: string X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '422': content: application/problem+json: examples: validation_error: value: detail: Request parameters or representation are invalid. errors: - code: validation_error detail: Request parameters or representation are invalid. pointer: / requestId: 29400000-0000-4000-8000-000000000001 status: 422 title: Request parameters or representation are invalid. type: https://docs.paypathiq.com/problems/validation_error schema: $ref: '#/components/schemas/Problem' description: Request parameters or representation are invalid. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Profile: description: Industry profile fixed by the current Integration grant. schema: const: credit_union.v1 type: string 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: The Integration has exceeded its current request limit. errors: - code: rate_limit_exceeded detail: >- The Integration has exceeded its current request limit. pointer: / requestId: 29400000-0000-4000-8000-000000000001 status: 429 title: The Integration has exceeded its current request limit. type: https://docs.paypathiq.com/problems/rate_limit_exceeded schema: $ref: '#/components/schemas/Problem' description: The Integration has exceeded its current request limit. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Profile: description: Industry profile fixed by the current Integration grant. schema: const: credit_union.v1 type: string X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string Retry-After: description: Seconds until this request may be retried. schema: minimum: 1 type: integer '500': content: application/problem+json: examples: internal_error: value: detail: An unexpected retryable error prevented a safe commit. errors: - code: internal_error detail: An unexpected retryable error prevented a safe commit. pointer: / requestId: 29400000-0000-4000-8000-000000000001 status: 500 title: An unexpected retryable error prevented a safe commit. type: https://docs.paypathiq.com/problems/internal_error schema: $ref: '#/components/schemas/Problem' description: An unexpected retryable error prevented a safe commit. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Profile: description: Industry profile fixed by the current Integration grant. schema: const: credit_union.v1 type: string X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '503': content: application/problem+json: examples: projection_unavailable: value: detail: >- The record could not be projected safely in this transaction. errors: - code: projection_unavailable detail: >- The record could not be projected safely in this transaction. pointer: / requestId: 29400000-0000-4000-8000-000000000001 status: 503 title: >- The record could not be projected safely in this transaction. type: https://docs.paypathiq.com/problems/projection_unavailable schema: $ref: '#/components/schemas/Problem' description: The record could not be projected safely in this transaction. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Profile: description: Industry profile fixed by the current Integration grant. schema: const: credit_union.v1 type: string 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}$ PaymentObservation: oneOf: - 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 effectiveAt: 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))$ externalReceivableId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ method: type: string enum: - bank_transfer - direct_debit - card - cash - cheque - unknown resultingRecoverableAmount: 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 sourceReference: type: string minLength: 1 maxLength: 200 type: type: string const: payment required: - amount - effectiveAt - externalReceivableId - method - resultingRecoverableAmount - sourceReference - type additionalProperties: false - 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 effectiveAt: 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))$ externalReceivableId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ method: type: string enum: - bank_transfer - direct_debit - card - cash - cheque - unknown resultingRecoverableAmount: 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 sourceReference: type: string minLength: 1 maxLength: 200 relatedExternalPaymentObservationId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ type: type: string const: refund required: - amount - effectiveAt - externalReceivableId - method - resultingRecoverableAmount - sourceReference - relatedExternalPaymentObservationId - type additionalProperties: false - 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 effectiveAt: 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))$ externalReceivableId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ method: type: string enum: - bank_transfer - direct_debit - card - cash - cheque - unknown resultingRecoverableAmount: 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 sourceReference: type: string minLength: 1 maxLength: 200 relatedExternalPaymentObservationId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ type: type: string const: reversal required: - amount - effectiveAt - externalReceivableId - method - resultingRecoverableAmount - sourceReference - relatedExternalPaymentObservationId - type additionalProperties: false description: >- Payment decreases and refund or reversal increases the locked Receivable balance; resultingRecoverableAmount must match exactly. PaymentObservationResponse: oneOf: - 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 effectiveAt: 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))$ externalReceivableId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ method: type: string enum: - bank_transfer - direct_debit - card - cash - cheque - unknown resultingRecoverableAmount: 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 sourceReference: type: string minLength: 1 maxLength: 200 type: type: string const: payment 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))$ externalPaymentObservationId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ required: - amount - effectiveAt - externalReceivableId - method - resultingRecoverableAmount - sourceReference - type - acceptedAt - externalPaymentObservationId additionalProperties: false - 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 effectiveAt: 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))$ externalReceivableId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ method: type: string enum: - bank_transfer - direct_debit - card - cash - cheque - unknown resultingRecoverableAmount: 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 sourceReference: type: string minLength: 1 maxLength: 200 relatedExternalPaymentObservationId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ type: type: string const: refund 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))$ externalPaymentObservationId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ required: - amount - effectiveAt - externalReceivableId - method - resultingRecoverableAmount - sourceReference - relatedExternalPaymentObservationId - type - acceptedAt - externalPaymentObservationId additionalProperties: false - 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 effectiveAt: 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))$ externalReceivableId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ method: type: string enum: - bank_transfer - direct_debit - card - cash - cheque - unknown resultingRecoverableAmount: 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 sourceReference: type: string minLength: 1 maxLength: 200 relatedExternalPaymentObservationId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ type: type: string const: reversal 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))$ externalPaymentObservationId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ required: - amount - effectiveAt - externalReceivableId - method - resultingRecoverableAmount - sourceReference - relatedExternalPaymentObservationId - type - acceptedAt - externalPaymentObservationId 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 ````