{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Receiving Return Requests","description":"Complete documentation for integrating Cheqi's digital receipt platform","keywords":["cheqi","digital receipts","api","sdk","java","javascript"],"llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"receiving-return-requests","__idx":0},"children":["Receiving Return Requests"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Customer return requests are encrypted for the original receipt issuer. Receive them in real time through a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETURN_REQUESTED"]}," webhook or retrieve outstanding requests from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /credit-note"]},"."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Encryption key required"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["API-key integrations use the company's registered encryption key. OAuth integrations use the client application's registered key. Decrypt with the private key that matches the registered public key."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"webhook-delivery","__idx":1},"children":["Webhook delivery"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Subscribe to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETURN_REQUESTED"]},". The event-specific payload is under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.creditNoteInitiationRequest"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"event\": \"RETURN_REQUESTED\",\n  \"data\": {\n    \"creditNoteInitiationRequest\": {\n      \"companyId\": \"550e8400-e29b-41d4-a716-446655440000\",\n      \"userId\": \"8c669f72-65bb-4788-9ab1-5289452e05d1\",\n      \"cheqiReceiptId\": \"CHQ-20260805-000001\",\n      \"publicKey\": \"base64-public-key...\",\n      \"encryptedCreditNoteInitiationRequest\": \"base64-ciphertext...\",\n      \"encryptedSymmetricKey\": \"base64-wrapped-aes-key...\",\n      \"clientId\": null,\n      \"created_at\": \"2026-08-05T12:30:00Z\"\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["companyId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["userId"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clientId"]}," identify the applicable routing context and can be absent when they do not apply. Verify the webhook signature before processing the request, acknowledge promptly with a 2xx response, and make processing idempotent because delivery can be retried."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/webhooks/setup"},"children":["Webhook Setup"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/webhooks/security"},"children":["Webhook Security"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"polling","__idx":2},"children":["Polling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the authenticated company or client-application credential:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl https://api.cheqi.io/credit-note \\\n  -H \"Authorization: Bearer <token>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The endpoint returns an array of outstanding requests:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"[\n  {\n    \"requestId\": \"d79f71c6-ef10-4cd1-92ca-750bfdb31a0c\",\n    \"cheqiReceiptId\": \"CHQ-20260805-000001\",\n    \"encryptedSymmetricKey\": \"base64-wrapped-aes-key...\",\n    \"publicKey\": \"base64-public-key...\",\n    \"status\": \"PENDING\",\n    \"createdAt\": \"2026-08-05T12:30:00Z\",\n    \"encryptedCreditNoteInitiationRequest\": \"base64-ciphertext...\"\n  }\n]\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Property"},"children":["Property"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requestId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["UUID"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Queue request identifier; use it for status updates."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cheqiReceiptId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cheqi identifier of the original receipt."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encryptedSymmetricKey"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["AES content key wrapped for the issuer's registered RSA public key."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["publicKey"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Public key associated with the encrypted request."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["enum"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PENDING"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCEPTED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PARTIALLY_ACCEPTED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REJECTED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCELLED"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createdAt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ISO 8601 date-time"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Time at which the request entered the queue."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encryptedCreditNoteInitiationRequest"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Base64-encoded encrypted plaintext request."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The polling response does not contain ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recipientId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["returnRequestId"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["receiverType"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encryptedCreditNote"]},", customer-detail ciphertext fields, or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["supplierPartyId"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"decrypting-with-an-sdk","__idx":3},"children":["Decrypting with an SDK"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Pass either the polling object or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook.data.creditNoteInitiationRequest"]}," to the decryption service."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","header":{"controls":{"copy":{}}},"source":"CreditNoteInitiationRequest request = sdk.getDecryptionService()\n    .decryptCreditNoteInitiationRequest(encryptedRequest, privateKeyBase64);\n\nString parentCheqiReceiptId = request.getCheqiReceiptId();\nfor (ReturnLineItem item : request.getLineItems()) {\n    String productId = item.getProductId();\n    BigDecimal quantity = item.getQuantity();\n    ReturnReasonCode reason = item.getReasonCode();\n    String explanation = item.getReasonDescription();\n}\n","lang":"java"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const request = sdk.decryptionService.decryptCreditNoteInitiationRequest(\n  encryptedRequest,\n  privateKeyBase64\n);\n\nconst parentCheqiReceiptId = request.cheqiReceiptId;\nfor (const item of request.lineItems) {\n  const { productId, quantity, reasonCode, reasonDescription } = item;\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The SDK decrypts, deserializes, and validates the plaintext contract. If you decrypt manually, validate it against the model below before acting on it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"decrypted-request-properties","__idx":4},"children":["Decrypted request properties"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"cheqiReceiptId\": \"CHQ-20260805-000001\",\n  \"receiptId\": \"INV-2026-0042\",\n  \"customerNote\": \"The left shoe is damaged.\",\n  \"lineItems\": [\n    {\n      \"productId\": \"SKU-AIRMAX-BLK-42\",\n      \"quantity\": 1,\n      \"reasonCode\": \"DAMAGED\",\n      \"reasonDescription\": \"Damage near the heel\"\n    }\n  ],\n  \"refundPreference\": \"ORIGINAL_PAYMENT_METHOD\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Property"},"children":["Property"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Rules"},"children":["Rules"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cheqiReceiptId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required, non-empty."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["receiptId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required, non-empty merchant receipt identifier."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerNote"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional; maximum 1,000 characters."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lineItems"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required and non-empty."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refundPreference"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ORIGINAL_PAYMENT_METHOD"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BANK_TRANSFER"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["STORE_CREDIT"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refundBankAccount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required only for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BANK_TRANSFER"]},"; forbidden for the other preferences."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each line needs a non-empty ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["productId"]}," of at most 255 characters, a positive ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["quantity"]},", and a valid ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reasonCode"]},". ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reasonDescription"]}," is optional and limited to 1,000 characters. Multiple lines may use the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["productId"]}," when different quantities have different reasons."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["productId"]}," is the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identifier"]}," supplied on the original receipt product. Use it with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["receiptId"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cheqiReceiptId"]}," to look up the authoritative original line, price, tax, and quantity in your own system."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"merchant-validation","__idx":5},"children":["Merchant validation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The return request describes what the customer wants; it does not authorize or calculate a refund. Before issuing a credit note:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm that the receipt and product belong to the requesting customer."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check the return window and your policy."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirm that the requested quantity does not exceed the remaining returnable quantity."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Calculate the accepted credit and tax from your authoritative transaction data."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Treat the refund preference as a request, not an instruction to move money automatically."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Validate bank details before using them."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"updating-request-status","__idx":6},"children":["Updating request status"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After making a decision, update the queue item using its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requestId"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X PATCH https://api.cheqi.io/credit-note/requests/d79f71c6-ef10-4cd1-92ca-750bfdb31a0c/status \\\n  -H \"Authorization: Bearer <token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"status\":\"ACCEPTED\"}'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PARTIALLY_ACCEPTED"]}," when only part of the requested return is approved, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REJECTED"]}," when none is approved, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]}," after the accepted return and refund workflow is finished."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-step","__idx":7},"children":["Next step"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Build the definitive merchant payload and issue the linked document in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/creditnote/issuing-credit-notes"},"children":["Issuing Credit Notes"]},"."]}]},"headings":[{"value":"Receiving Return Requests","id":"receiving-return-requests","depth":1},{"value":"Webhook delivery","id":"webhook-delivery","depth":2},{"value":"Polling","id":"polling","depth":2},{"value":"Decrypting with an SDK","id":"decrypting-with-an-sdk","depth":2},{"value":"Decrypted request properties","id":"decrypted-request-properties","depth":2},{"value":"Merchant validation","id":"merchant-validation","depth":2},{"value":"Updating request status","id":"updating-request-status","depth":2},{"value":"Next step","id":"next-step","depth":2}],"frontmatter":{"title":"Receiving Return Requests","description":"Receive, decrypt, and validate customer return requests","seo":{"title":"Receiving Return Requests"}},"lastModified":"2026-08-05T15:06:40.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/creditnote/receiving-returns","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}