{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Return Webhooks","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":"return-webhooks","__idx":0},"children":["Return Webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Return webhooks cover two distinct encrypted flows:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A customer sends an encrypted return request to the original issuer (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETURN_REQUESTED"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An issuer creates a credit note through the device-generation flow, and an elected owner device encrypts the generated document bundle for downstream recipients (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CREDIT_NOTE_CREATED"]},")."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The backend routes both ciphertext types without decrypting them."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"subscribe","__idx":1},"children":["Subscribe"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"name\": \"Returns integration\",\n  \"notificationUrl\": \"https://your-domain.example/webhooks/cheqi\",\n  \"events\": [\n    \"RETURN_REQUESTED\",\n    \"CREDIT_NOTE_CREATED\"\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"return_requested","__idx":2},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["RETURN_REQUESTED"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"event\": \"RETURN_REQUESTED\",\n  \"data\": {\n    \"creditNoteInitiationRequest\": {\n      \"clientId\": \"issuer-public-client-id\",\n      \"companyId\": \"550e8400-e29b-41d4-a716-446655440000\",\n      \"userId\": \"8ccf09a7-d969-4a09-880f-42d520a0999a\",\n      \"created_at\": \"2026-08-03T14:00:00Z\",\n      \"cheqiReceiptId\": \"CHQ-20260803-ABC123\",\n      \"publicKey\": \"base64-issuer-public-key...\",\n      \"encryptedCreditNoteInitiationRequest\": \"base64-ciphertext...\",\n      \"encryptedSymmetricKey\": \"base64-wrapped-aes-key...\"\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The customer device created this encrypted request for the original receipt issuer. Unwrap ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encryptedSymmetricKey"]},", decrypt ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encryptedCreditNoteInitiationRequest"]},", and deserialize the plaintext as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CreditNoteInitiationRequest"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The plaintext contract contains:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cheqiReceiptId"]},": Cheqi identifier of the original receipt."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["receiptId"]},": issuer-supplied identifier of the original receipt."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerNote"]},": optional customer note."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lineItems"]},": requested quantities and return reasons."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refundPreference"]},": preferred refund method."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refundBankAccount"]},": supplied only when required for a bank-transfer preference."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This request is not a credit note and is not a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ReceiptEnvelope"]},". Validate it against your records and return policy before issuing a credit note."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"issue-through-the-new-credit-note-flow","__idx":3},"children":["Issue through the new credit-note flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When accepting a return, issue the credit note through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /credit-note/encrypted"]},":"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Resolve the original owner's current devices."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Encrypt the credit-note generation input independently for every returned device recipient."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Submit the encrypted generation request with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["parentCheqiReceiptId"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Owner devices generate and store their local CHEQI credit note."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["One elected device builds and encrypts downstream ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ReceiptEnvelope"]}," bundles."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cheqi sends ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CREDIT_NOTE_CREATED"]}," after those encrypted deliveries are accepted."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not use the legacy ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EncryptedCreditNoteDto"]}," delivery shape. It is not part of the current webhook contract."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"credit_note_created","__idx":4},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CREDIT_NOTE_CREATED"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"event\": \"CREDIT_NOTE_CREATED\",\n  \"data\": {\n    \"encryptedCreditNote\": {\n      \"clientId\": \"your-public-client-id\",\n      \"companyId\": \"550e8400-e29b-41d4-a716-446655440000\",\n      \"created_at\": \"2026-08-03T15:00:00Z\",\n      \"cheqiReceiptId\": \"CHQ-CN-20260803-DEF456\",\n      \"encryptedEnvelope\": \"base64-ciphertext...\",\n      \"encryptedEnvelopeKey\": \"base64-wrapped-aes-key...\",\n      \"publicKey\": \"base64-recipient-public-key-snapshot...\",\n      \"recipientKeyAlgorithm\": \"RSA_2048\",\n      \"envelopeVersion\": 1,\n      \"receiptGeneratorVersion\": \"0.3.0\",\n      \"finalHash\": \"sha256-cheqi-credit-note-hash...\"\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Decrypt ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encryptedEnvelope"]}," with the same SDK envelope implementation used for receipt webhooks. The plaintext is a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ReceiptEnvelope"]}," whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["documents"]}," map contains:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CHEQI"]}," always."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UBL_CREDIT_NOTE"]}," when required by the recipient's accepted formats."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["documents"]}," map is authoritative. There is no separate format list or customer-details ciphertext."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["finalHash"]}," is the definitive CHEQI credit-note hash submitted by the elected device together with the encrypted deliveries. A separate finalization event is not required."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"operational-guidance","__idx":5},"children":["Operational guidance"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Cheqi-Signature"]}," using the exact raw request body."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Persist the event before returning ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2xx"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Process asynchronously and idempotently."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Keep historical private keys available for deliveries encrypted before a key rotation."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Never log decrypted return requests, document envelopes, or unwrapped AES keys."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/webhooks/events"},"children":["Webhook Events"]}," for the shared event contract and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/webhooks/security"},"children":["Webhook Security"]}," for signature verification."]}]},"headings":[{"value":"Return Webhooks","id":"return-webhooks","depth":1},{"value":"Subscribe","id":"subscribe","depth":2},{"value":"RETURN_REQUESTED","id":"return_requested","depth":2},{"value":"Issue through the new credit-note flow","id":"issue-through-the-new-credit-note-flow","depth":2},{"value":"CREDIT_NOTE_CREATED","id":"credit_note_created","depth":2},{"value":"Operational guidance","id":"operational-guidance","depth":2}],"frontmatter":{"seo":{"title":"Return Webhooks"}},"lastModified":"2026-08-03T14:23:19.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/webhooks/return-webhooks","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}