> ## 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 a hosted payment request > Requires payment_requests:write, a scope separate from intake and financial reporting. Creates a fixed-amount, fixed-allocation hosted payment request for one Customer and returns a secret link to the payment page on the Client's verified payment domain, where card details are entered with the Client's payment provider; raw card data never passes through this API. Each amount must equal the Receivable's exact current working balance, the Customer must be liable for every Receivable, and the Client must have an active payment domain and a single active merchant account. The request is rejected before any payment attempt exists when amounts are stale, a Receivable is not payable, the source feed is stale, current policy or a hold prevents a payment request, a payment is already in progress, or the merchant is not configured. Creating a request replaces the Customer's earlier unpaid hosted request. The payer confirms a contact detail held for the Customer before paying. The attempt starts only when the payer submits the hosted page, which re-checks the same balances. Only the provider's verified confirmation marks the request paid and reduces working balances; returning from the hosted page, an unknown outcome or a repeated event never does. Loan connections request loan Receivables and service-charge connections request service-charge demands; the payer page labels each item by its financial type. Creating a request, and each later status change, is announced as payment_request.created or payment_request.updated in the change feed. The link expires after one hour. Exact retries return 200 with a fresh link while the request is open; conflicting reuse returns 409 payment_request_conflict. ## OpenAPI ````yaml /generated/inbound-api-v1.openapi.json put /v1/clients/{clientCode}/payment-requests/{externalPaymentRequestId} 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-requests/{externalPaymentRequestId}: put: tags: - Payment requests summary: Create a hosted payment request description: >- Requires payment_requests:write, a scope separate from intake and financial reporting. Creates a fixed-amount, fixed-allocation hosted payment request for one Customer and returns a secret link to the payment page on the Client's verified payment domain, where card details are entered with the Client's payment provider; raw card data never passes through this API. Each amount must equal the Receivable's exact current working balance, the Customer must be liable for every Receivable, and the Client must have an active payment domain and a single active merchant account. The request is rejected before any payment attempt exists when amounts are stale, a Receivable is not payable, the source feed is stale, current policy or a hold prevents a payment request, a payment is already in progress, or the merchant is not configured. Creating a request replaces the Customer's earlier unpaid hosted request. The payer confirms a contact detail held for the Customer before paying. The attempt starts only when the payer submits the hosted page, which re-checks the same balances. Only the provider's verified confirmation marks the request paid and reduces working balances; returning from the hosted page, an unknown outcome or a repeated event never does. Loan connections request loan Receivables and service-charge connections request service-charge demands; the payer page labels each item by its financial type. Creating a request, and each later status change, is announced as payment_request.created or payment_request.updated in the change feed. The link expires after one hour. Exact retries return 200 with a fresh link while the request is open; conflicting reuse returns 409 payment_request_conflict. operationId: putPaymentRequest 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, opaque identifier of this hosted payment request. Reusing it with the identical body is a safe retry; reusing it with a different body conflicts. in: path name: externalPaymentRequestId required: true schema: $ref: '#/components/schemas/ExternalResourceId' requestBody: description: One uncompressed resource representation, limited to 256 KiB. content: application/json: example: externalCustomerId: CUS_EXAMPLE items: - amount: amount: '125.50' currency: EUR externalReceivableId: REC_EXAMPLE schema: $ref: '#/components/schemas/PaymentRequest' required: true responses: '200': content: application/json: example: externalCustomerId: CUS_EXAMPLE items: - amount: amount: '125.50' currency: EUR externalReceivableId: REC_EXAMPLE createdAt: '2026-10-15T12:00:00Z' expiresAt: '2026-10-15T13:00:00Z' externalPaymentRequestId: PAYREQ_EXAMPLE revision: 1 paymentUrl: https://pay.client.example/payment/EXAMPLE_ONE_TIME_TOKEN status: open totalAmount: amount: '125.50' currency: EUR schema: $ref: '#/components/schemas/PaymentRequestResponse' description: Identical retry of the accepted request. 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: externalCustomerId: CUS_EXAMPLE items: - amount: amount: '125.50' currency: EUR externalReceivableId: REC_EXAMPLE createdAt: '2026-10-15T12:00:00Z' expiresAt: '2026-10-15T13:00:00Z' externalPaymentRequestId: PAYREQ_EXAMPLE revision: 1 paymentUrl: https://pay.client.example/payment/EXAMPLE_ONE_TIME_TOKEN status: open totalAmount: amount: '125.50' currency: EUR schema: $ref: '#/components/schemas/PaymentRequestResponse' description: Payment request created; no payment attempt exists yet. 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 '409': content: application/problem+json: examples: dependency_missing: value: detail: >- The Customer or a Receivable is missing from the authorized scope. requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: >- The Customer or a Receivable is missing from the authorized scope. type: https://docs.paypathiq.com/problems/dependency_missing payment_attempt_in_progress: value: detail: >- A payment attempt is already in progress for one of the Receivables. requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: >- A payment attempt is already in progress for one of the Receivables. type: >- https://docs.paypathiq.com/problems/payment_attempt_in_progress payment_merchant_unconfigured: value: detail: >- The Client has no active payment domain and single active merchant for this environment, or hosted payments are not enabled. requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: >- The Client has no active payment domain and single active merchant for this environment, or hosted payments are not enabled. type: >- https://docs.paypathiq.com/problems/payment_merchant_unconfigured payment_request_conflict: value: detail: This identity already has a different payment request. requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: This identity already has a different payment request. type: >- https://docs.paypathiq.com/problems/payment_request_conflict payment_request_held: value: detail: >- Current policy, a Dispute, a restriction, a reconciliation hold or stale source evidence prevents new payment initiation. requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: >- Current policy, a Dispute, a restriction, a reconciliation hold or stale source evidence prevents new payment initiation. type: https://docs.paypathiq.com/problems/payment_request_held payment_request_not_payable: value: detail: >- The Customer is not liable, a Receivable is not payable now, or the Customer cannot verify a payment. requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: >- The Customer is not liable, a Receivable is not payable now, or the Customer cannot verify a payment. type: >- https://docs.paypathiq.com/problems/payment_request_not_payable payment_request_stale: value: detail: An amount no longer equals the current working balance. requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: An amount no longer equals the current working balance. type: https://docs.paypathiq.com/problems/payment_request_stale payment_request_unsupported: value: detail: >- The connection's industry profile does not match the Client's type, so hosted payment requests are unavailable. requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: >- The connection's industry profile does not match the Client's type, so hosted payment requests are unavailable. type: >- https://docs.paypathiq.com/problems/payment_request_unsupported schema: $ref: '#/components/schemas/Problem' description: >- The Customer or a Receivable is missing from the authorized scope. A payment attempt is already in progress for one of the Receivables. The Client has no active payment domain and single active merchant for this environment, or hosted payments are not enabled. This identity already has a different payment request. Current policy, a Dispute, a restriction, a reconciliation hold or stale source evidence prevents new payment initiation. The Customer is not liable, a Receivable is not payable now, or the Customer cannot verify a payment. An amount no longer equals the current working balance. The connection's industry profile does not match the Client's type, so hosted payment requests 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}$ PaymentRequest: type: object properties: externalCustomerId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ description: >- The paying Customer. The Customer must be liable for every listed Receivable. items: minItems: 1 maxItems: 25 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 current working balance of this Receivable. A request cannot pay part of a Receivable, more than it, or a different Receivable. externalReceivableId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ required: - amount - externalReceivableId additionalProperties: false description: >- The Receivables and amounts the hosted payment page may collect. Each Receivable may appear once. required: - externalCustomerId - items additionalProperties: false PaymentRequestResponse: type: object properties: createdAt: 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))$ expiresAt: anyOf: - 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))$ - type: 'null' description: >- When the most recent payment link stops working. Null once the request is no longer open. externalCustomerId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ description: >- Caller-assigned, opaque identifier for this Customer's source-system record. It is not a PayPathIQ ID, member number, loan or account number, or contact detail. Keep it stable when Customer details change. externalPaymentRequestId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ items: 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 current working balance of this Receivable. A request cannot pay part of a Receivable, more than it, or a different Receivable. externalReceivableId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ required: - amount - externalReceivableId additionalProperties: false paymentUrl: anyOf: - type: string format: uri - type: 'null' description: >- Hosted payment page on the Client's verified payment domain. It is a secret: send it only to the paying Customer. Returned by create and by an exact retry while the request is open; null on reads. revision: type: integer minimum: 1 maximum: 9007199254740991 description: >- Increases each time the request's status changes. It matches the revision in change-feed events. status: type: string enum: - open - payment_in_progress - under_review - paid - expired - replaced - cancelled description: >- paid is set only after the payment provider's verified confirmation. Returning from the hosted page never changes this status. totalAmount: 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: - createdAt - expiresAt - externalCustomerId - externalPaymentRequestId - items - paymentUrl - revision - status - totalAmount 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.