> For the complete documentation index, see [llms.txt](https://docs.a-pay.one/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.a-pay.one/api-documentation/api-integration/lost-transaction/create-lost-transaction.md). # Create lost transaction ## Create new lost transaction > Either \`order\_id\` or \`custom\_transaction\_id\` must be set. ```json {"openapi":"3.0.3","info":{"title":"A-Pay","version":"1.0.0"},"tags":[{"name":"Lost transaction","description":"Lost transactions"}],"servers":[{"url":"https://"}],"security":[{"apikey":[]}],"components":{"securitySchemes":{"apikey":{"type":"apiKey","name":"apikey","in":"header"}}},"paths":{"/Remotes/create-lost-transaction":{"post":{"summary":"Create new lost transaction","description":"Either `order_id` or `custom_transaction_id` must be set.","tags":["Lost transaction"],"parameters":[{"in":"query","name":"project_id","schema":{"type":"number"},"description":"Project ID in the A-Pay system","required":true}],"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"title":"File","type":"string","format":"binary","description":"Supported file formats: `jpg`, `png`, `heic`, `jpeg`, `pdf`."},"order_id":{"description":"Deposit ID in the A-Pay system","maxLength":16,"minLength":16,"pattern":"^[0-9a-f]+$","title":"Order Id","type":"string"},"custom_transaction_id":{"default":null,"description":"Transaction ID in the client's system","maxLength":200,"minLength":1,"title":"Custom Transaction Id","type":"string"},"description":{"default":null,"description":"Description of a lost transaction","maxLength":100000,"minLength":1,"title":"Description","type":"string"}},"required":["file"]}}}},"responses":{"200":{"content":{"application/json":{"schema":{"title":"Success","type":"object","properties":{"success":{"type":"boolean","description":"`true` if there are no errors"},"status":{"type":"string","enum":["Pending"],"description":"Lost transaction status"},"order_id":{"description":"Lost transaction ID in the A-Pay system","maxLength":16,"minLength":16,"pattern":"^[0-9a-f]+$","title":"Order Id","type":"string"},"custom_transaction_id":{"description":"Transaction ID in the client's system","maxLength":200,"minLength":1,"title":"Custom Transaction Id","type":"string"},"message":{"type":"string","default":"Transaction successfully created","title":"Message","description":"Description of response"}},"required":["success","status","order_id","custom_transaction_id","message"]}}},"description":"Success"},"400":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Validation error","properties":{"success":{"type":"boolean","description":"`false` if an error occurred"},"message":{"type":"string","description":"Description of error"},"code":{"type":"number","description":"Error code in the A-Pay system"},"target":{"type":"string","enum":["form_data","query"]},"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string","description":"Description of error"},"location":{"type":"array","description":"Path to the field where the error occurred","items":{"type":"string"}}},"required":["message","location"]}}},"required":["success","message","code","target","errors"]},{"type":"object","title":"Lost transaction was already created","properties":{"success":{"type":"boolean","default":false},"code":{"type":"integer","default":400},"message":{"type":"string","description":"Lost transaction was already created"}},"required":["code","error","success","message"]},{"type":"object","title":"Daily limit has been reached","properties":{"success":{"type":"boolean","default":false},"code":{"type":"integer","default":400},"message":{"type":"string","description":"Daily limit has been reached"}},"required":["code","error","success","message"]},{"type":"object","title":"Invalid value","properties":{"success":{"type":"boolean","default":false},"code":{"type":"integer","default":400},"field":{"type":"string","default":"order_id","enum":["order_id","custom_transaction_id"],"description":"Field name"},"message":{"type":"string","default":"Invalid value: order id","enum":["Invalid value: order id","Invalid value: custom transaction id"],"description":"Invalid value"}},"required":["code","field","success","message"]}]}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"title":"Unathorized","type":"object","properties":{"code":{"type":"integer","default":401},"message":{"type":"string","default":"Unauthorized"},"success":{"type":"boolean","default":false}},"required":["code","error","success","message"]}}},"description":"Unauthorized"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","title":"Transaction was not found","properties":{"success":{"type":"boolean","default":false},"code":{"type":"integer","default":404},"message":{"type":"string","description":"Transaction was not found"}},"required":["code","error","success","message"]}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Field required","properties":{"success":{"type":"boolean","description":"`false` if an error occurred"},"message":{"type":"string","default":"Field required","description":"You must specify at least one file to upload"},"code":{"type":"number","description":"Error code in the A-Pay system"}},"required":["success","message","code"]},{"type":"object","title":"File too large","properties":{"success":{"type":"boolean","description":"`false` if an error occurred"},"message":{"type":"string","default":"File too large","description":"File must be less than 20mb"},"code":{"type":"number","description":"Error code in the A-Pay system"}},"required":["success","message","code"]},{"type":"object","title":"No more than max amount files allowed","properties":{"success":{"type":"boolean","description":"`false` if an error occurred"},"message":{"type":"string","default":"No more than max amount files allowed: 16","description":"No more than max amount files allowed: 16"},"code":{"type":"number","description":"Error code in the A-Pay system"}},"required":["success","message","code"]},{"type":"object","title":"File has unknown type","properties":{"success":{"type":"boolean","description":"`false` if an error occurred"},"message":{"type":"string","default":"File has unknown type","description":"Supported file formats: `jpg`, `png`, `heic`, `jpeg`, `pdf`."},"code":{"type":"number","description":"Error code in the A-Pay system"}},"required":["success","message","code"]}]}}}}}}}}} ``` ## ⚠️ Error Handling Guide The following section describes possible error responses for the `POST /Remotes/create-lost-transaction` endpoint and how you can resolve them by yourself.
400 Bad Request – Validation Errors #### **When it happens:** * `order_id` or `custom_transaction_id` is missing or has an invalid format * Field values do not meet length or pattern requirements #### **How to resolve it:** The response body contains detailed information about what went wrong.\ Make sure to inspect the following fields in the JSON response: | Field | Description | | ------------------- | ------------------------------------------------------------------------------------------- | | `target` | Indicates which part of the request failed (e.g. `"form_data"`, `"query"`) | | `errors[].message` | Description of what exactly is wrong (e.g., “ensure this value has at least 16 characters”) | | `errors[].location` | Path to the field that caused the error (e.g., `["order_id"]`) |
400 Bad Request – Duplicate Request #### **When it happens:** A lost transaction issue has already been created for the same ID. #### **How to resolve it:** Use `GET /lost-transaction-info` to check existing issue status
401 Unauthorized #### **When it happens:** Missing or incorrect API key in the request. #### **How to resolve it:** * Include the header: `Authorization: Bearer YOUR_API_KEY` * Check that your key is valid and linked to the correct `project_id`
404 Not Found #### **When it happens:** The provided `order_id` or `custom_transaction_id` does not match any transaction. #### **How to resolve it:** * Check that you’re sending the correct ID * Confirm the transaction exists in your system * Contact our support team if you're certain the payment was made
422 Unprocessable Entity – File Upload Issues #### **When it happens:** Issues with the uploaded `file` field: * Missing file * Unsupported file format * File size too large * Too many files #### **How to resolve it:** * Make sure the uploaded file is in one of the supported formats: `jpg`, `png`, `heic`, `jpeg`, `pdf` * Ensure the file size does not exceed **20 MB** * Attach **no more than 16 files** in a single request
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.a-pay.one/api-documentation/api-integration/lost-transaction/create-lost-transaction.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.