Migration guide: v2.1 → v2.2

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

Read this page if you 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 Changelog.

What does not change:

• URLs — the same base URLs and the same endpoints.
• Authentication — the same POST /auth/token, Authorization, ApplicationToken and DigitalSignature.
• Webhook event names — CASHIN_* and CASHOUT_* keep their names, including CASHIN_REQUESTED, CASHOUT_REQUESTED and CASHOUT_FAILED. What changes is the data inside some of them.

Breaking changes

In the tables below, Before is what v2.1 returned or documented, and After is the v2.2 contract.

Cash-Out

The rule behind the statuses: if the money never left your account, it is CANCELLED; if it left and came back, it is REFUNDED.

Cash-In

Webhooks

Every Cash-Out field change in the table above applies to the webhooks too: webhook data is the same object as GET /cash-out/{id}.

Errors

The authentication errors are described in Authentication Errors.

Summary

GET /cash-out/summary:

GET /cash-in/summary does not change: the Cash-In paid bucket is still paid. The reconciliation formula becomes cashOut.totals.completed.amount where it used cashOut.totals.paid.amount — see Reconciliation.

Behavior changes

These do not break a correct integration, but you may see different values than before.

• expiredAt is the charge's expiration date and time (the end of the payment window), with the same value on GET /cash-in/{id}, GET /cash-in and CASHIN_EXPIRED. In v2.1 the value could differ between channels. The envelope eventAt is the send time, not the expiration.
• Cash-In webhook data follows the GET rules, amount included: the data of every Cash-In event (except CASHIN_REQUESTED) is the same object GET /cash-in/{id} returns at that moment. The one documented difference is on refunded Cash-Ins — see Event Structure.
• settlement appears only when a bank is involved. Cash-In: on PAID and REFUNDED, now also in the data of CASHIN_PAID and CASHIN_REFUNDED. Cash-Out: on COMPLETED and REFUNDED, and on CANCELLED when a bank had already been assigned (no money left your account). Never on PROCESSING or PENDING.
• X-Idempotency-Key is optional (still recommended) on POST /cash-in and POST /cash-out. Without it the request is processed normally, and externalReference still blocks duplicates.
• 409 DUPLICATED_EXTERNAL_REFERENCE also on POST /cash-in, as on POST /cash-out.

Additions

• reason on refunded Cash-Outs and Cash-Ins, as a code.
• settlement in the data of CASHIN_PAID and CASHIN_REFUNDED.
• A code on every error except the authentication 401s: VALIDATION_ERROR, CASHIN_NOT_FOUND, CASHOUT_NOT_FOUND, REFUND_NOT_ALLOWED, MISSING_E2E, INTERNAL_ERROR and the DigitalSignature codes. See Error Handling.
• GET /cash-in/{id} and GET /cash-out/{id} accept your externalReference, besides internalCode, transactionId and the payment or refund endToEndId. When a value matches more than one transaction, a fixed precedence decides: internalCode, then transactionId, then payment endToEndId, then refund endToEndId, then externalReference; within the same level, the most recent transaction wins.
• Idempotent-Replayed: true header when a request with the same X-Idempotency-Key and the same body is replayed within 24 hours.
• Idempotency error codes: 400 IDEMPOTENCY_KEY_INVALID, 409 IDEMPOTENCY_KEY_IN_PROGRESS, 422 IDEMPOTENCY_KEY_REUSED. See Idempotency.

Checklist for integrators

Search your code for each item and apply the action.

Side-by-side example

The same cancelled Cash-Out, delivered as CASHOUT_FAILED. All data is fictitious.

v2.1

{
  "eventType": "CASHOUT_FAILED",
  "eventAt": "2026-03-10T14:00:20Z",
  "data": {
    "transactionId": "3f9a1c52-7b64-4d0e-9a1b-2c8e5f7d4a10",
    "internalCode": "QWERT12345",
    "externalReference": "withdraw_example_001",
    "status": "FAILED",
    "amount": 500.00,
    "failure": {
      "code": "REJECTED",
      "message": "Transferência rejeitada pela instituição recebedora."
    },
    "payee": {
      "name": "Maria Silva",
      "document": "12345678909",
      "destination": {
        "type": "PIX",
        "pixKeyType": "CPF/CNPJ",
        "pixKey": "12345678909"
      }
    },
    "requestedAt": "2026-03-10T14:00:00-03:00",
    "failedAt": "2026-03-10T14:00:15-03:00"
  }
}

v2.2

{
  "eventType": "CASHOUT_FAILED",
  "eventAt": "2026-03-10T14:00:20Z",
  "data": {
    "transactionId": "3f9a1c52-7b64-4d0e-9a1b-2c8e5f7d4a10",
    "internalCode": "QWERT12345",
    "externalReference": "withdraw_example_001",
    "status": "CANCELLED",
    "amount": 500.00,
    "failure": {
      "code": "PAYEE_BANK_REJECTED",
      "message": "The receiving institution rejected the transfer."
    },
    "payee": {
      "name": "Maria Silva",
      "document": "12345678909",
      "destination": {
        "type": "PIX",
        "pixKeyType": "CPF",
        "pixKey": "12345678909"
      }
    },
    "settlement": {
      "ispb": "87654321",
      "bank": "SETTLEMENT PARTNER B",
      "branch": "0001",
      "account": "654987"
    },
    "requestedAt": "2026-03-10T14:00:00-03:00",
    "cancelledAt": "2026-03-10T14:00:15-03:00"
  }
}

What changed: status FAILED → CANCELLED; failure.code REJECTED → PAYEE_BANK_REJECTED, with its fixed English message; pixKeyType CPF/CNPJ → CPF; failedAt → cancelledAt; and settlement is present because a bank had already been assigned. No money left the account in either version.