> ## 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. # Create or replace a Receivable > Contract preview: Public API hostnames are not live yet; this operation is not currently runnable. Creates or fully replaces one Receivable. Lifecycle status is response-only and changes through explicit commands. ## OpenAPI ````yaml /generated/inbound-api-v1.openapi.json put /v1/clients/{clientCode}/receivables/{externalReceivableId} 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}/receivables/{externalReceivableId}: put: tags: - Receivables summary: Create or replace a Receivable description: >- Contract preview: Public API hostnames are not live yet; this operation is not currently runnable. Creates or fully replaces one Receivable. Lifecycle status is response-only and changes through explicit commands. operationId: putReceivable 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 case-sensitive Receivable identifier supplied by the Integration. in: path name: externalReceivableId required: true schema: $ref: '#/components/schemas/ExternalResourceId' requestBody: content: application/json: example: balanceBreakdown: costs: amount: '0.00' currency: EUR fees: amount: '50.00' currency: EUR interest: amount: '200.00' currency: EUR principal: amount: '1000.00' currency: EUR creditUnion: arrearsAmount: amount: '1250.00' currency: EUR contractualInstalment: amount: amount: '125.00' currency: EUR frequency: monthly defaultDate: '2026-07-01' loanAccountReference: loan-ref-example loanType: personal_loan totalOutstandingAmount: amount: '4000.00' currency: EUR dueDate: '2026-08-01' recoverableAmount: amount: '1250.00' currency: EUR responsibleParties: - externalPartyId: PTY_123 role: primary sourceReference: receivable-ref-example schema: $ref: '#/components/schemas/Receivable' description: 'Maximum uncompressed request body size: 256 KiB.' required: true responses: '200': content: application/json: example: balanceBreakdown: costs: amount: '0.00' currency: EUR fees: amount: '50.00' currency: EUR interest: amount: '200.00' currency: EUR principal: amount: '1000.00' currency: EUR creditUnion: arrearsAmount: amount: '1250.00' currency: EUR contractualInstalment: amount: amount: '125.00' currency: EUR frequency: monthly defaultDate: '2026-07-01' loanAccountReference: loan-ref-example loanType: personal_loan totalOutstandingAmount: amount: '4000.00' currency: EUR dueDate: '2026-08-01' recoverableAmount: amount: '1250.00' currency: EUR responsibleParties: - externalPartyId: PTY_123 role: primary sourceReference: receivable-ref-example externalReceivableId: REC_123 status: active updatedAt: '2026-08-29T12:00:00Z' schema: $ref: '#/components/schemas/ReceivableResponse' description: Receivable replaced, or request was an identical safe retry. 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: balanceBreakdown: costs: amount: '0.00' currency: EUR fees: amount: '50.00' currency: EUR interest: amount: '200.00' currency: EUR principal: amount: '1000.00' currency: EUR creditUnion: arrearsAmount: amount: '1250.00' currency: EUR contractualInstalment: amount: amount: '125.00' currency: EUR frequency: monthly defaultDate: '2026-07-01' loanAccountReference: loan-ref-example loanType: personal_loan totalOutstandingAmount: amount: '4000.00' currency: EUR dueDate: '2026-08-01' recoverableAmount: amount: '1250.00' currency: EUR responsibleParties: - externalPartyId: PTY_123 role: primary sourceReference: receivable-ref-example externalReceivableId: REC_123 status: active updatedAt: '2026-08-29T12:00:00Z' schema: $ref: '#/components/schemas/ReceivableResponse' description: Receivable created 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: dependency_missing: value: detail: >- A referenced Party does not exist in this Integration and Client scope. errors: - code: dependency_missing detail: >- A referenced Party does not exist in this Integration and Client scope. pointer: / requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: >- A referenced Party does not exist in this Integration and Client scope. type: https://docs.paypathiq.com/problems/dependency_missing schema: $ref: '#/components/schemas/Problem' description: >- A referenced Party does not exist in this Integration and Client scope. 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}$ Receivable: type: object properties: balanceBreakdown: type: object properties: costs: 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 fees: 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 interest: 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 principal: 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: - costs - fees - interest - principal additionalProperties: false description: >- All four amounts are required when a breakdown is supplied; use 0.00 where needed. creditUnion: type: object properties: arrearsAmount: 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 contractualInstalment: 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 frequency: type: string enum: - weekly - fortnightly - monthly - quarterly - annual required: - amount - frequency additionalProperties: false defaultDate: type: string format: date 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])))$ loanAccountReference: type: string minLength: 1 maxLength: 200 loanType: type: string enum: - personal_loan - mortgage - overdraft - credit_card - business_loan - other totalOutstandingAmount: 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: - loanAccountReference - loanType additionalProperties: false dueDate: type: string format: date 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])))$ receivableSafetyAssertions: maxItems: 3 type: array items: type: object properties: 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))$ state: type: string enum: - active - cleared type: type: string enum: - dispute - complaint - statute_barred required: - effectiveAt - state - type additionalProperties: false description: At most one assertion per type; ordering is semantically irrelevant. recoverableAmount: 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 responsibleParties: minItems: 1 maxItems: 8 type: array items: type: object properties: externalPartyId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ description: >- Caller-assigned, opaque identifier for this Party's source-system record. It is not a PayPathIQ ID, customer or member number, loan or account number, or contact detail. Keep it stable when Party details change. role: type: string enum: - primary - joint - guarantor required: - externalPartyId - role additionalProperties: false description: >- Party identifiers must be unique and exactly one role must be primary. sourceReference: type: string minLength: 1 maxLength: 200 required: - creditUnion - dueDate - recoverableAmount - responsibleParties - sourceReference additionalProperties: false description: The balance breakdown must sum exactly to recoverableAmount. ReceivableResponse: type: object properties: balanceBreakdown: type: object properties: costs: 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 fees: 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 interest: 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 principal: 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: - costs - fees - interest - principal additionalProperties: false description: >- All four amounts are required when a breakdown is supplied; use 0.00 where needed. creditUnion: type: object properties: arrearsAmount: 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 contractualInstalment: 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 frequency: type: string enum: - weekly - fortnightly - monthly - quarterly - annual required: - amount - frequency additionalProperties: false defaultDate: type: string format: date 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])))$ loanAccountReference: type: string minLength: 1 maxLength: 200 loanType: type: string enum: - personal_loan - mortgage - overdraft - credit_card - business_loan - other totalOutstandingAmount: 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: - loanAccountReference - loanType additionalProperties: false dueDate: type: string format: date 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])))$ receivableSafetyAssertions: maxItems: 3 type: array items: type: object properties: 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))$ state: type: string enum: - active - cleared type: type: string enum: - dispute - complaint - statute_barred required: - effectiveAt - state - type additionalProperties: false description: At most one assertion per type; ordering is semantically irrelevant. recoverableAmount: 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 responsibleParties: minItems: 1 maxItems: 8 type: array items: type: object properties: externalPartyId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ description: >- Caller-assigned, opaque identifier for this Party's source-system record. It is not a PayPathIQ ID, customer or member number, loan or account number, or contact detail. Keep it stable when Party details change. role: type: string enum: - primary - joint - guarantor required: - externalPartyId - role additionalProperties: false description: >- Party identifiers must be unique and exactly one role must be primary. sourceReference: type: string minLength: 1 maxLength: 200 externalReceivableId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ status: type: string enum: - active - paused - closed updatedAt: 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: - creditUnion - dueDate - recoverableAmount - responsibleParties - sourceReference - externalReceivableId - status - updatedAt additionalProperties: false description: The balance breakdown must sum exactly to recoverableAmount. 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 ````