{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Migration guide: v2.1 → v2.2","description":"Official developer documentation for ConnectPSP's PIX payment gateway API.","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":"migration-guide-v21--v22","__idx":0},"children":["Migration guide: v2.1 → v2.2"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Read this page if you ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["already integrate with the API v2"]}," and your code handles Cash-Outs, Cash-Ins,"," ","webhooks or error responses. It lists what changed in v2.2 and what to change in your code. The full list of"," ","changes is in the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/changelog"},"children":["Changelog"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What does not change:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["URLs"]}," — the same base URLs and the same endpoints."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Authentication"]}," — the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /auth/token"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ApplicationToken"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DigitalSignature"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Webhook event names"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHIN_*"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHOUT_*"]}," keep their names, including ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHIN_REQUESTED"]},","," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHOUT_REQUESTED"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHOUT_FAILED"]},". What changes is the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," inside some of them."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"breaking-changes","__idx":1},"children":["Breaking changes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the tables below, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Before"]}," is what v2.1 returned or documented, and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["After"]}," is the v2.2 contract."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"cash-out","__idx":2},"children":["Cash-Out"]},{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Before (v2.1)"},"children":["Before (v2.1)"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"After (v2.2)"},"children":["After (v2.2)"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," — paid"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAID"]}," (and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]},", documented as a legacy synonym)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," — money never left"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$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":["status"]}," — held on the ConnectPSP side"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ANALYSING"]}," could appear"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PENDING"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," — full list"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PROCESSING"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PENDING"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAID"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REFUNDED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCELLED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PROCESSING"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PENDING"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCELLED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REFUNDED"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Payment date"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paidAt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completedAt"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Failure date"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failedAt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Removed. A cancelled Cash-Out carries ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelledAt"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cancellation date"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["canceledAt"]}," (one L)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelledAt"]}," (two L, like the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCELLED"]}," status)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failure"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["On ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Only"]}," on ",{"$$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":["failure.code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REJECTED"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GENERIC_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One code from a fixed catalog of 18 codes — see the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/webhooks#failure-codes"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failure.code"]}," table"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failure.message"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Free text, in Portuguese"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fixed per ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]},", in English"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reason"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Free text"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A code, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["only"]}," on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REFUNDED"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYEE_REQUESTED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FRAUD"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OPERATIONAL_ERROR"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REVERSED_BY_INSTITUTION"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OTHER"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payee.destination.pixKeyType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"CPF/CNPJ\""]}," for a document key"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CPF"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CNPJ"]},". The full list is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CPF"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CNPJ"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EMAIL"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PHONE"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EVP"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Insufficient balance on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /cash-out"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code: \"INSUFFICIENT_FUNDS\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202 Accepted"]},", then ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHOUT_FAILED"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failure.code: \"INSUFFICIENT_FUNDS\""]},". Never a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalReference"]}," maximum length"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["100 characters (documented)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["50 characters"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The rule behind the statuses: if the money never left your account, it is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCELLED"]},"; if it left and came"," ","back, it is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REFUNDED"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"cash-in","__idx":3},"children":["Cash-In"]},{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Before (v2.1)"},"children":["Before (v2.1)"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"After (v2.2)"},"children":["After (v2.2)"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cancellation date"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["canceledAt"]}," (one L)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelledAt"]}," (two L). ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCELLED"]}," is now documented on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /cash-in/{id}"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reason"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not returned"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A code, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["only"]}," on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REFUNDED"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FRAUD"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DUPLICATED_PAYMENT"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CUSTOMER_REQUEST"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MERCHANT_ERROR"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYER_NOT_ALLOWED"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OTHER"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalReference"]}," maximum length"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["100 characters (documented)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["50 characters"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"webhooks","__idx":4},"children":["Webhooks"]},{"$$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":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Before (v2.1)"},"children":["Before (v2.1)"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"After (v2.2)"},"children":["After (v2.2)"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHIN_REQUESTED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.status: \"REQUESTED\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.status: \"AWAITING_PAYMENT\""]},", as on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /cash-in"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /cash-in/{id}"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHOUT_REQUESTED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.status: \"REQUESTED\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.status: \"PROCESSING\""]},", as on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /cash-out"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /cash-out/{id}"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHOUT_COMPLETED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.status: \"COMPLETED\""]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completedAt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No change in these fields — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /cash-out/{id}"]}," now uses them too. Adds ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["settlement"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHOUT_FAILED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.status: \"FAILED\""]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failure.code"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REJECTED"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GENERIC_ERROR"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failedAt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Same event name. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.status: \"CANCELLED\""]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failure"]}," from the catalog, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelledAt"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHOUT_REFUNDED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reason"]}," as free text"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reason"]}," as a code. Adds ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["settlement"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHIN_REFUNDED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reason"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reason"]}," as a code"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every Cash-Out field change in the table above applies to the webhooks too: webhook ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," is the same object"," ","as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /cash-out/{id}"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"errors","__idx":5},"children":["Errors"]},{"$$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":"Case"},"children":["Case"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Before (v2.1 documentation)"},"children":["Before (v2.1 documentation)"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"After (v2.2)"},"children":["After (v2.2)"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Wrong credentials on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /auth/token"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401 INVALID_CREDENTIALS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ \"message\": \"...\" }"]},", a plain object with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["JWT expired"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401 TOKEN_EXPIRED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["no body"]}," and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WWW-Authenticate"]}," header (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error_description=\"The token expired at '...'\""]},"). Request a new token"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["JWT missing or invalid"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["no body"]}," and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WWW-Authenticate"]}," header"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ApplicationToken"]}," missing or invalid"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401 INVALID_APPLICATION_TOKEN"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," Problem Details with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}]},"; tell the cases apart by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DigitalSignature"]}," missing or wrong"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422 INVALID_SIGNATURE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401 DIGITAL_SIGNATURE_REQUIRED"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401 DIGITAL_SIGNATURE_INVALID"]},"; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403 CRYPTO_TOKEN_NOT_CONFIGURED"]}," when your client has no CryptoToken"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Insufficient balance on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /cash-out"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422 INSUFFICIENT_FUNDS"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not an HTTP error: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHOUT_FAILED"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failure.code: \"INSUFFICIENT_FUNDS\""]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["PIX key not found on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /cash-out"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422 PIX_KEY_NOT_FOUND"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not an HTTP error: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHOUT_FAILED"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failure.code: \"PIX_KEY_NOT_FOUND\""]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction not found"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404 NOT_FOUND"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404 CASHIN_NOT_FOUND"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404 CASHOUT_NOT_FOUND"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Refund of a Cash-In that cannot be refunded"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422 CASH_IN_NOT_PAID"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASH_IN_ALREADY_REFUNDED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASH_IN_EXPIRED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASH_IN_CANCELLED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422 REFUND_NOT_ALLOWED"]},"; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["detail"]}," says which case"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Refund before the payment E2E is available"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422 MISSING_END_TO_END_ID"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422 MISSING_E2E"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The authentication errors are described in ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/error-handling#authentication-errors"},"children":["Authentication Errors"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"summary","__idx":6},"children":["Summary"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /cash-out/summary"]},":"]},{"$$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":"Bucket"},"children":["Bucket"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Before (v2.1)"},"children":["Before (v2.1)"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"After (v2.2)"},"children":["After (v2.2)"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Paid"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totals.paid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totals.completed"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Failed"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totals.failed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Removed. Counted under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totals.cancelled"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Full list of keys"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processing"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paid"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failed"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refunded"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processing"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completed"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refunded"]}," — the Cash-Out statuses in lowercase"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["settlement"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Paid transactions"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completed"]}," only"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /cash-in/summary"]}," does not change: the Cash-In paid bucket is still ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paid"]},". The reconciliation formula"," ","becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cashOut.totals.completed.amount"]}," where it used ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cashOut.totals.paid.amount"]}," — see"," ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/reconciliation"},"children":["Reconciliation"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"behavior-changes","__idx":7},"children":["Behavior changes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These do not break a correct integration, but you may see different values than before."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expiredAt"]}," is the charge's expiration date and time"]}," (the end of the payment window), with the same value"," ","on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /cash-in/{id}"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /cash-in"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHIN_EXPIRED"]},". In v2.1 the value could differ between channels."," ","The envelope ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eventAt"]}," is the send time, not the expiration."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Cash-In webhook ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," follows the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}," rules"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," included: the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," of every Cash-In event"," ","(except ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHIN_REQUESTED"]},") is the same object ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /cash-in/{id}"]}," returns at that moment. The one documented"," ","difference is on refunded Cash-Ins — see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/webhooks#event-structure"},"children":["Event Structure"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["settlement"]}," appears only when a bank is involved."]}," Cash-In: on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAID"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REFUNDED"]},", now also in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," ","of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHIN_PAID"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHIN_REFUNDED"]},". Cash-Out: on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REFUNDED"]},", and on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCELLED"]}," when a bank"," ","had already been assigned (no money left your account). Never on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PROCESSING"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PENDING"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Idempotency-Key"]}," is optional"]}," (still recommended) on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /cash-in"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /cash-out"]},". Without it the"," ","request is processed normally, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalReference"]}," still blocks duplicates."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409 DUPLICATED_EXTERNAL_REFERENCE"]}," also on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /cash-in"]}]},", as on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /cash-out"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"additions","__idx":8},"children":["Additions"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reason"]}]}," on refunded Cash-Outs and Cash-Ins, as a code."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["settlement"]}]}," in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHIN_PAID"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHIN_REFUNDED"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," on every error"]}," except the authentication ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]},"s: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VALIDATION_ERROR"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHIN_NOT_FOUND"]},","," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHOUT_NOT_FOUND"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REFUND_NOT_ALLOWED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MISSING_E2E"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INTERNAL_ERROR"]}," and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DigitalSignature"]}," codes. See"," ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/error-handling"},"children":["Error Handling"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /cash-in/{id}"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /cash-out/{id}"]}," accept your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalReference"]}]},", besides ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalCode"]},","," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionId"]}," and the payment or refund ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["endToEndId"]},". When a value matches more than one transaction, a fixed"," ","precedence decides: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internalCode"]},", then ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionId"]},", then payment ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["endToEndId"]},", then refund ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["endToEndId"]},","," ","then ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalReference"]},"; within the same level, the most recent transaction wins."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotent-Replayed: true"]}]}," header when a request with the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Idempotency-Key"]}," and the same body is"," ","replayed within 24 hours."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Idempotency error codes"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400 IDEMPOTENCY_KEY_INVALID"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409 IDEMPOTENCY_KEY_IN_PROGRESS"]},","," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422 IDEMPOTENCY_KEY_REUSED"]},". See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/authentication#idempotency"},"children":["Idempotency"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"checklist-for-integrators","__idx":9},"children":["Checklist for integrators"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Search your code for each item and apply the action."]},{"$$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":"Search for"},"children":["Search for"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Where"},"children":["Where"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Action"},"children":["Action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAID"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cash-Out status handling"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Replace with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETED"]},". Keep ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAID"]}," for Cash-In, where it does not change"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cash-Out status handling"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Replace with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCELLED"]},". The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHOUT_FAILED"]}," event name stays"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ANALYSING"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cash-Out status handling"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Remove. Treat the stage as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PENDING"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paidAt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cash-Out"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completedAt"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failedAt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cash-Out"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelledAt"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["canceledAt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cash-Out and Cash-In"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelledAt"]}," (two L)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REJECTED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GENERIC_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failure.code"]}," handling"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Map the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/webhooks#failure-codes"},"children":["18 catalog codes"]},". Treat a code you do not know as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PROCESSING_ERROR"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Parsing of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failure.message"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cash-Out"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Key your logic on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failure.code"]},". The message is fixed English text"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Parsing of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reason"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cash-Out"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reason"]}," as a code, only on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REFUNDED"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CPF/CNPJ"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pixKeyType"]}," handling"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Accept ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CPF"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CNPJ"]}," as separate values"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"REQUESTED\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHIN_REQUESTED"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHOUT_REQUESTED"]}," handlers"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Expect ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AWAITING_PAYMENT"]}," (Cash-In) and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PROCESSING"]}," (Cash-Out)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totals.paid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /cash-out/summary"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totals.completed"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totals.failed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /cash-out/summary"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totals.cancelled"]},", where failed Cash-Outs are now counted"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INSUFFICIENT_FUNDS"]}," on the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /cash-out"]}," response"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cash-Out creation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Move the handling to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHOUT_FAILED"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failure.code: \"INSUFFICIENT_FUNDS\""]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PIX_KEY_NOT_FOUND"]}," on the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /cash-out"]}," response"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cash-Out creation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Move the handling to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHOUT_FAILED"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failure.code: \"PIX_KEY_NOT_FOUND\""]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_CREDENTIALS"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOKEN_EXPIRED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_APPLICATION_TOKEN"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authentication handling"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Handle by status and endpoint: a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WWW-Authenticate"]}," header means a new JWT is needed. See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/error-handling#authentication-errors"},"children":["Authentication Errors"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_SIGNATURE"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DigitalSignature"]}," handling"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Handle ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401 DIGITAL_SIGNATURE_REQUIRED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401 DIGITAL_SIGNATURE_INVALID"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403 CRYPTO_TOKEN_NOT_CONFIGURED"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NOT_FOUND"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASH_IN_*"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MISSING_END_TO_END_ID"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Error handling"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHIN_NOT_FOUND"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHOUT_NOT_FOUND"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REFUND_NOT_ALLOWED"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MISSING_E2E"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalReference"]}," generation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cash-In and Cash-Out creation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Keep it at 50 characters or fewer"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"side-by-side-example","__idx":10},"children":["Side-by-side example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The same cancelled Cash-Out, delivered as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASHOUT_FAILED"]},". All data is fictitious."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["v2.1"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"eventType\": \"CASHOUT_FAILED\",\n  \"eventAt\": \"2026-03-10T14:00:20Z\",\n  \"data\": {\n    \"transactionId\": \"3f9a1c52-7b64-4d0e-9a1b-2c8e5f7d4a10\",\n    \"internalCode\": \"QWERT12345\",\n    \"externalReference\": \"withdraw_example_001\",\n    \"status\": \"FAILED\",\n    \"amount\": 500.00,\n    \"failure\": {\n      \"code\": \"REJECTED\",\n      \"message\": \"Transferência rejeitada pela instituição recebedora.\"\n    },\n    \"payee\": {\n      \"name\": \"Maria Silva\",\n      \"document\": \"12345678909\",\n      \"destination\": {\n        \"type\": \"PIX\",\n        \"pixKeyType\": \"CPF/CNPJ\",\n        \"pixKey\": \"12345678909\"\n      }\n    },\n    \"requestedAt\": \"2026-03-10T14:00:00-03:00\",\n    \"failedAt\": \"2026-03-10T14:00:15-03:00\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["v2.2"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"eventType\": \"CASHOUT_FAILED\",\n  \"eventAt\": \"2026-03-10T14:00:20Z\",\n  \"data\": {\n    \"transactionId\": \"3f9a1c52-7b64-4d0e-9a1b-2c8e5f7d4a10\",\n    \"internalCode\": \"QWERT12345\",\n    \"externalReference\": \"withdraw_example_001\",\n    \"status\": \"CANCELLED\",\n    \"amount\": 500.00,\n    \"failure\": {\n      \"code\": \"PAYEE_BANK_REJECTED\",\n      \"message\": \"The receiving institution rejected the transfer.\"\n    },\n    \"payee\": {\n      \"name\": \"Maria Silva\",\n      \"document\": \"12345678909\",\n      \"destination\": {\n        \"type\": \"PIX\",\n        \"pixKeyType\": \"CPF\",\n        \"pixKey\": \"12345678909\"\n      }\n    },\n    \"settlement\": {\n      \"ispb\": \"87654321\",\n      \"bank\": \"SETTLEMENT PARTNER B\",\n      \"branch\": \"0001\",\n      \"account\": \"654987\"\n    },\n    \"requestedAt\": \"2026-03-10T14:00:00-03:00\",\n    \"cancelledAt\": \"2026-03-10T14:00:15-03:00\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["What changed: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FAILED"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCELLED"]},"; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failure.code"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REJECTED"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYEE_BANK_REJECTED"]},", with its fixed"," ","English message; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pixKeyType"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CPF/CNPJ"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CPF"]},"; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failedAt"]}," → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelledAt"]},"; and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["settlement"]}," is present because"," ","a bank had already been assigned. No money left the account in either version."]}]},"headings":[{"value":"Migration guide: v2.1 → v2.2","id":"migration-guide-v21--v22","depth":1},{"value":"Breaking changes","id":"breaking-changes","depth":2},{"value":"Cash-Out","id":"cash-out","depth":3},{"value":"Cash-In","id":"cash-in","depth":3},{"value":"Webhooks","id":"webhooks","depth":3},{"value":"Errors","id":"errors","depth":3},{"value":"Summary","id":"summary","depth":3},{"value":"Behavior changes","id":"behavior-changes","depth":2},{"value":"Additions","id":"additions","depth":2},{"value":"Checklist for integrators","id":"checklist-for-integrators","depth":2},{"value":"Side-by-side example","id":"side-by-side-example","depth":2}],"frontmatter":{"seo":{"title":"Migration guide: v2.1 → v2.2"}},"lastModified":"2026-10-05T16:29:38.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/migration-v2-2","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}