> For the complete documentation index, see [llms.txt](https://docs.qiro.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qiro.fi/developer-section/openapi-spec/repayments/prepare-the-next-repayment-transaction.md).

# Prepare the next repayment transaction

Refreshes current dues and returns the next unsigned transaction. This endpoint is normally called by the SDK after a `TOKEN_APPROVAL` transaction confirms, or to retry an expired preparation. Approval and `REPAYMENT` amounts use the fixed maximum established when the repayment resource was created. If fresh dues exceed that fixed maximum, Qiro fails the repayment with `REPAYMENT_QUOTE_EXPIRED` and the partner must create a fresh repayment.

```json
{"openapi":"3.1.0","info":{"title":"Qiro Partner Instant Settlement API","version":"1.0.0-draft"},"tags":[{"name":"Repayments","description":"Preview, prepare, and track full repayment of one funded drawdown."}],"servers":[{"url":"/","description":"Qiro API host supplied to the partner during onboarding."}],"security":[{"oauth2":["repayments:write"]}],"components":{"securitySchemes":{"oauth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"facilities:read":"Read facilities owned by the authenticated partner.","drawdowns:read":"Read partner drawdown resources.","drawdowns:write":"Create and prepare partner drawdowns.","repayments:read":"Read dues quotes and repayment resources.","repayments:write":"Create and prepare repayments.","closures:read":"Read facility closure dues and closure resources.","closures:write":"Create and prepare facility closures."}}}}},"parameters":{"RepaymentId":{"name":"repayment_id","in":"path","required":true,"description":"Stable Qiro identifier for one drawdown repayment workflow.","schema":{"type":"string","pattern":"^rpy_[A-Za-z0-9]+$"}},"OptionalCorrelationId":{"name":"X-Correlation-ID","in":"header","required":false,"description":"Optional end-to-end request identifier. The SDK supplies one automatically; Qiro generates and echoes one when absent.","schema":{"type":"string","minLength":1,"maxLength":128}}},"schemas":{"RepaymentPreparation":{"type":"object","additionalProperties":false,"required":["repayment_id","status","action","sequence","amount_base_units","maximum_repayment_base_units","expires_at","transaction"],"properties":{"repayment_id":{"type":"string","pattern":"^rpy_[A-Za-z0-9]+$"},"status":{"$ref":"#/components/schemas/RepaymentStatus"},"action":{"type":"string","enum":["TOKEN_APPROVAL","REPAYMENT"]},"sequence":{"type":"integer","minimum":1},"amount_base_units":{"$ref":"#/components/schemas/UnsignedIntegerString"},"maximum_repayment_base_units":{"$ref":"#/components/schemas/UnsignedIntegerString"},"expires_at":{"type":"string","format":"date-time"},"transaction":{"$ref":"#/components/schemas/UnsignedTransaction"}}},"RepaymentStatus":{"type":"string","enum":["READY_FOR_SUBMISSION","SUBMITTING","CONFIRMING","REPAID","FAILED"]},"UnsignedIntegerString":{"type":"string","pattern":"^(0|[1-9]\\d*)$"},"UnsignedTransaction":{"type":"object","additionalProperties":false,"required":["chain_id","to","data","value"],"properties":{"chain_id":{"type":"integer","minimum":1},"to":{"$ref":"#/components/schemas/EvmAddress"},"data":{"type":"string","pattern":"^0x(?:[a-fA-F0-9]{2})*$"},"value":{"$ref":"#/components/schemas/UnsignedIntegerString"}}},"EvmAddress":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Safe human-readable explanation."},"request_id":{"type":"string"},"correlation_id":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object","additionalProperties":true},"issues":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"BadRequest":{"description":"Invalid schema, field format, or correlation identifier.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"The bearer token is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"The authenticated partner does not own the resource or lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ResourceNotFound":{"description":"The requested workflow resource was not found for the authenticated partner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ResourceConflict":{"description":"Idempotency, workflow state, or verified facility identity conflicts with the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"EligibilityRejected":{"description":"The request is valid but rejected by facility, policy, liquidity, or contract rules.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServiceUnavailable":{"description":"Contract, RPC, subgraph, or reconciliation infrastructure is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/v1/repayments/{repayment_id}/prepare":{"post":{"tags":["Repayments"],"operationId":"prepareRepayment","summary":"Prepare the next repayment transaction","description":"Refreshes current dues and returns the next unsigned transaction. This endpoint is normally\ncalled by the SDK after a `TOKEN_APPROVAL` transaction confirms, or to retry an expired\npreparation. Approval and `REPAYMENT` amounts use the fixed maximum established when the\nrepayment resource was created. If fresh dues exceed that fixed maximum, Qiro fails the\nrepayment with `REPAYMENT_QUOTE_EXPIRED` and the partner must create a fresh repayment.\n","parameters":[{"$ref":"#/components/parameters/RepaymentId"},{"$ref":"#/components/parameters/OptionalCorrelationId"}],"responses":{"200":{"description":"Next unsigned transaction in the repayment flow.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RepaymentPreparation"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/ResourceNotFound"},"409":{"$ref":"#/components/responses/ResourceConflict"},"422":{"$ref":"#/components/responses/EligibilityRejected"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}}}}
```
