{
  "openapi": "3.0.3",
  "info": {
    "title": "ZAPPY API",
    "version": "1.0.0",
    "description": "The ZAPPY API lets a partner platform hold a banking account, receive money through PIX, read its\nstatement and balance, and pay money out — either to a PIX key or to a bank account.\n\nThis reference documents the **public HTTP surface only**. Everything else ZAPPY runs is internal\ngRPC between services and is not reachable from the internet.\n\n# Getting started\n\nThere are two separate APIs behind one hostname, and they do **not** share a credential type.\n\n| Surface | Base path | Who calls it | Credential |\n| --- | --- | --- | --- |\n| Identity | `/iam/v1/auth` | a person signing in to the ZAPPY panel | `Authorization: Bearer <JWT>` |\n| Banking | `/baas/v1/account/{account_id}` | your server, unattended | `Authorization: Basic <base64(client_id:client_secret)>` |\n\nIf you are building a server-to-server integration, **the banking API is the one you want**, and a\nBasic credential is the only thing you need. The identity endpoints exist because the ZAPPY panel\nis a public client; they are documented here for completeness and for partners embedding a\nsign-in flow.\n\nMixing the two is the most common first failure:\n\n- Sending `Bearer` to a banking endpoint returns `401` `ZPY.AUT.009` — *Basic authorization is required*.\n- Sending `Basic` to `DELETE /iam/v1/auth/logout` returns `401` `INVALID_CREDENTIALS` — *user credentials required*.\n\n## Base URLs\n\n| Environment | Base URL | Notes |\n| --- | --- | --- |\n| Sandbox | `https://api.sdx.zappy.com.br` | isolated data and credentials — **start here** |\n| Production | `https://api.zappy.com.br` | real money |\n\n**Every code sample on this page targets the sandbox**, so you can copy one and run it as-is.\nChange the host to go live; nothing else about a request differs between the two.\n\nSandbox and production share nothing — not accounts, not credentials, not balances. A sandbox\n`client_id` will not authenticate against production, and a sandbox payout moves no real money.\n\n## Your first request\n\n```bash\ncurl -sS https://api.sdx.zappy.com.br/baas/v1/account/$ACCOUNT_ID/balance \\\n  -u \"$CLIENT_ID:$CLIENT_SECRET\"\n```\n\n```json\n{ \"balance\": 1520.75, \"blocked\": 0.00, \"updated_at\": \"2026-09-22T13:40:11Z\" }\n```\n\n# Authentication\n\n## Banking credentials (Basic)\n\nYour `client_id` and `client_secret` are issued by ZAPPY and scoped to either **one account** or\n**one company**. A company-scoped credential can act on every account that company owns; an\naccount-scoped credential can act on exactly one. Anything else is `403`.\n\nThe secret is shown **once**, at issuance, and only its digest is stored. If it is lost it must be\nre-issued, not recovered.\n\nSend it as standard HTTP Basic:\n\n```\nAuthorization: Basic base64(client_id + \":\" + client_secret)\n```\n\n### Permissions\n\nEvery banking endpoint additionally requires a permission on your credential, written\n`resource:action`. Actions are hierarchical — holding `manage` implies `write`, and `write`\nimplies `read`.\n\n| Resource | Used by |\n| --- | --- |\n| `balance` | account balance |\n| `transaction` | statement, PIX transaction lookup |\n| `withdraw` | creating and reading payouts |\n| `pix_key` | listing and reading PIX keys |\n| `qrcode` | reading a PIX QR code |\n\nA credential missing the permission gets `403` `ZPY.AUT.010`.\n\n### Account preconditions\n\nBefore any banking call succeeds, the account must be both `active` and `verified`. If it is not,\nthe call fails with **`400`** — not `403`:\n\n- `ZPY.ACC.002` — *Account is not active*\n- `ZPY.ACC.003` — *Account is not verified*\n\n## Identity credentials (Bearer)\n\n`POST /iam/v1/auth/login` returns either a full session or a second-factor challenge. When the\nuser has TOTP enrolled, the first response carries **only** `mfa_required` and `mfa_token` — no\nname, no e-mail, no roles. Exchange the challenge at `POST /iam/v1/auth/mfa` for the real session.\n\nAccess tokens are short-lived. `POST /iam/v1/auth/refresh` **rotates**: it revokes the presented\nrefresh token and issues a new pair. A refresh token is therefore single-use — never call refresh\nconcurrently from two places for the same session, or one of them will be signed out.\n\n`expires_at` is **Unix epoch seconds**, not a timestamp string.\n\n# Conventions\n\n## Money\n\nMonetary values are JSON **numbers in reais with exactly two decimals** — `10.50`, never `\"10.50\"`\nand never `1050`. Parse them as a decimal type, not a float, if your language distinguishes.\n\n## Timestamps and dates\n\n- Timestamps are RFC 3339 in UTC: `2026-09-22T13:40:11Z`. An absent timestamp is `\"\"`, not `null`.\n- Date-only inputs (`init`, `ends`, `date`) are `YYYY-MM-DD`.\n\n## Pagination\n\nEndpoints that paginate accept `page` (1-based, default `1`) and `limit` (default `25`).\n\nA `limit` above `100` is **silently clamped to 100** rather than rejected. A `page` or `limit`\nbelow `1`, or a non-numeric value, is a `400` `ZPY.VAL.009`.\n\nResponses carry:\n\n```json\n{ \"data\": [], \"meta\": { \"page\": 1, \"limit\": 25, \"total\": 0 } }\n```\n\n`GET /pix/keys` is the exception — it does not paginate and returns only `meta.total`.\n\n## Date windows\n\n`GET /transactions` and `GET /withdraws` **require** `init` and `ends`. Both bounds are inclusive,\nso `init == ends` is a single day. The window may not run backwards and may not exceed **90 days**\n(`ZPY.VAL.008`).\n\n## Responses and errors\n\nSuccessful responses are the resource itself at the top level — there is no `data` envelope on a\nsingle object.\n\nErrors always use one shape:\n\n```json\n{\n  \"code\": \"ZPY.VAL.006\",\n  \"message\": \"account_id must be a UUID\",\n  \"trace_id\": \"0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31\"\n}\n```\n\n`trace_id` also comes back as the `X-Trace-ID` response header on **every** request. Send your own\n`X-Trace-ID` and it is echoed and propagated. **Quote it in any support request** — it is how the\ncall is found in our logs.\n\n### Read the status, not only the code\n\n`ZPY.AUT.010` is returned for both `401` (*Invalid Basic credentials*) and `403` (*You are not\nauthorized to access this resource*). Branch on the HTTP status; treat the code as detail.\n\n### Error codes\n\n| Code | Status | Meaning |\n| --- | --- | --- |\n| `ZPY.AUT.001` | 401 | Authorization header missing |\n| `ZPY.AUT.002` | 401 | Authorization header malformed |\n| `ZPY.AUT.009` | 401 | Basic authorization required (you sent something else) |\n| `ZPY.AUT.010` | 401 / 403 | Invalid credentials, or credentials lacking the permission |\n| `ZPY.VAL.001` | 400 | A required field or query parameter is missing |\n| `ZPY.VAL.006` | 400 | A path identifier is not a UUID |\n| `ZPY.VAL.007` | 400 | A date is not `YYYY-MM-DD` |\n| `ZPY.VAL.008` | 400 | Date range invalid, over 90 days, or a scheduled date |\n| `ZPY.VAL.009` | 400 | A numeric value is not a positive integer, or an amount is not above zero |\n| `ZPY.VAL.011` | 400 | Payload malformed, tax number invalid, or a text field over 1024 characters |\n| `ZPY.ACC.001` | 404 | Account not found, or not visible to this credential |\n| `ZPY.ACC.002` | 400 | Account is not active |\n| `ZPY.ACC.003` | 400 | Account is not verified |\n| `ZPY.ACC.005` | 403 / 422 / 502 | Provider read-only, not configured, or unreachable |\n| `ZPY.ACC.006` | 502 | Balance could not be retrieved from the provider |\n| `ZPY.ACC.007` | 502 | Statement could not be retrieved from the provider |\n| `ZPY.PIX.002` | 404 / 502 | PIX key not found, or keys could not be listed |\n| `ZPY.PIX.005` | 404 / 502 | QR code not found or expired |\n| `ZPY.PIX.007` | 502 | PIX transaction could not be retrieved |\n| `ZPY.PIX.010` | 400 / 403 / 502 | Payout rejected or could not be processed |\n| `ZPY.PIX.011` | 404 | Payout not found |\n| `ZPY.PIX.012` | 400 | Payout method invalid, or `qrcode` which is unsupported |\n| `ZPY.PIX.013` | 400 | Bank number, branch and account required for a `bank_account` payout |\n| `ZPY.PIX.014` | 400 | Key type and key required for a `pix` payout |\n| `ZPY.PIX.017` | 404 | PIX transaction not found |\n| `ZPY.PIX.018` | 501 | Payout cancellation is not implemented |\n| `ZPY.SYS.001` | 500 | Unexpected internal error |\n| `ZPY.SYS.002` | 503 | Authentication service unavailable — retry with backoff |\n\nA `502` means a banking provider failed, not that your request was wrong. Retry those with\nexponential backoff; do **not** retry a `4xx` unchanged.\n\n# Flows\n\n## Receiving money through PIX\n\nZAPPY creates PIX QR codes for you; that step is not on this public API today. Once a charge\nexists you own its `reference`, and this API is how you follow it.\n\n```\n  your server                    ZAPPY                     payer\n      |                            |                         |\n      |  GET /pix/qrcode/{ref}     |                         |\n      |--------------------------->|                         |\n      |  emv payload + expires_at  |                         |\n      |<---------------------------|                         |\n      |                            |                         |\n      |  show qrcode.hash ------------------------------------>  pays in their bank app\n      |                            |                         |\n      |  GET /pix/transactions/{ref}                         |\n      |--------------------------->|                         |\n      |  status: paid, e2e_id, payer                         |\n      |<---------------------------|                         |\n```\n\n1. `GET /pix/qrcode/{reference}` returns the charge. `qrcode.hash` is the EMV\n   copy-and-paste payload — render it as a QR image or offer it as text. Honour `expires_at`.\n2. `GET /pix/transactions/{reference}` resolves the payment. While the charge is unpaid this\n   returns the charge in a pending state; once settled it carries `paid_at`, the `e2e_id`\n   (the Central Bank's end-to-end identifier) and the `payer`.\n3. The credit also appears in `GET /transactions` as an `operation` of `Pix In`.\n\nAn anonymous charge has no `payer` block. Do not assume it is present.\n\n## Paying money out\n\n```\n  your server                         ZAPPY                      provider\n      |                                 |                           |\n      |  POST /withdraw                 |                           |\n      |  {method, reference, value, …}  |                           |\n      |-------------------------------->|  validate, debit, submit  |\n      |                                 |-------------------------->|\n      |  202-shaped body:               |                           |\n      |  status \"processing\"            |                           |\n      |<--------------------------------|                           |\n      |                                 |                           |\n      |  GET /withdraw/{reference}      |                           |\n      |-------------------------------->|                           |\n      |  status, e2e_id, origin, destination                        |\n      |<--------------------------------|                           |\n```\n\n1. Choose `method`: `pix` (send to a PIX key) or `bank_account` (send to branch and account).\n   `qrcode` is **not supported** and is rejected with `ZPY.PIX.012`.\n2. `reference` is **yours**. Generate a unique, stable value per payout and keep it — it is how\n   you look the payout up afterwards, and how you avoid paying twice if a response is lost.\n3. `date` must be **today in UTC**. Scheduled payouts are rejected with `ZPY.VAL.008`.\n4. `destination.tax_number` must be a valid CPF (11 digits) or CNPJ (14 digits). Punctuation is\n   stripped before validation, so both `123.456.789-09` and `12345678909` are accepted.\n5. The response is always `status: \"processing\"`. Settlement is asynchronous — poll\n   `GET /withdraw/{reference}`, or read `GET /withdraws` for the window.\n\n> **Payout cancellation is not available.** `DELETE /withdraw/{reference}` exists in the route\n> table and always returns `501` `ZPY.PIX.018`. Treat a submitted payout as final.\n\n## Reconciling\n\n`GET /transactions` returns the account statement for a date window, newest first, alongside the\nbalance and the account's own bank coordinates. Each entry carries `operation` (`Pix In` /\n`Pix Out`), a `type` of `credit` or `debit`, and `tags` holding the provider identifier and the\nend-to-end identifier when the provider supplied them.\n\n`document_number` is `0` when the provider's identifier is not numeric. Do not treat `0` as a\nvalid document number.\n\n# Support\n\nInclude the `X-Trace-ID` of the failing call, the endpoint, and the UTC timestamp. For a payout,\ninclude your `reference` — never the `client_secret`.",
    "contact": {
      "name": "ZAPPY Developer Support",
      "url": "https://developer.zappy.com.br/"
    },
    "termsOfService": "https://zappy.com.br/"
  },
  "servers": [
    {
      "url": "https://api.sdx.zappy.com.br",
      "description": "Sandbox — isolated data and credentials. Every sample on this page targets it."
    },
    {
      "url": "https://api.zappy.com.br",
      "description": "Production — real money."
    }
  ],
  "tags": [
    {
      "name": "Authentication",
      "description": "Sign-in, second factor, session rotation and password recovery for people using the ZAPPY panel. Server-to-server integrations do not need these."
    },
    {
      "name": "Accounts",
      "description": "Balance and statement for one account."
    },
    {
      "name": "Payouts",
      "description": "Moving money out, to a PIX key or a bank account."
    },
    {
      "name": "PIX keys",
      "description": "The PIX keys registered to an account."
    },
    {
      "name": "PIX QR codes",
      "description": "Reading a charge and its EMV payload."
    },
    {
      "name": "PIX transactions",
      "description": "Resolving a charge to its payment."
    }
  ],
  "x-tagGroups": [
    {
      "name": "Identity",
      "tags": [
        "Authentication"
      ]
    },
    {
      "name": "Banking",
      "tags": [
        "Accounts",
        "Payouts"
      ]
    },
    {
      "name": "PIX",
      "tags": [
        "PIX keys",
        "PIX QR codes",
        "PIX transactions"
      ]
    }
  ],
  "paths": {
    "/baas/v1/account/{account_id}/balance": {
      "get": {
        "tags": [
          "Accounts"
        ],
        "summary": "Get the account balance",
        "description": "Current balance and the portion held and not yet available for payout.\n\nRead live from the banking provider, so a `502` here means the provider failed, not that the request was wrong.",
        "operationId": "getAccountBalance",
        "security": [
          {
            "TokenBasic": []
          }
        ],
        "parameters": [
          {
            "name": "account_id",
            "in": "path",
            "required": true,
            "description": "The ZAPPY account this call acts on. Must be a UUID your credential is scoped to.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77"
          }
        ],
        "responses": {
          "200": {
            "description": "The balance.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountBalanceResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed, or the account is not active and verified.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.ACC.003",
                  "message": "Account is not verified",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, or non-Basic credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.AUT.009",
                  "message": "Basic authorization is required",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required permission, or is scoped to another account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.AUT.010",
                  "message": "You are not authorized to access this resource",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "404": {
            "description": "Account not found, or not visible to this credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.ACC.001",
                  "message": "Account not found",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "502": {
            "description": "The provider could not be reached.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.ACC.006",
                  "message": "Failed to retrieve account balance",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "503": {
            "description": "The authentication service is unavailable. Retry with backoff.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.SYS.002",
                  "message": "Authentication service is unavailable",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "cURL",
            "source": "curl -sS -X GET \"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/balance\" \\\n  -u \"$CLIENT_ID:$CLIENT_SECRET\"\n"
          },
          {
            "lang": "Go",
            "label": "Go",
            "source": "package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/balance\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.SetBasicAuth(clientID, clientSecret)\n\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\n\tpayload, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.StatusCode, string(payload))\n}\n"
          },
          {
            "lang": "PHP",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init(\"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/balance\");\ncurl_setopt($ch, CURLOPT_CUSTOMREQUEST, \"GET\");\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_setopt($ch, CURLOPT_USERPWD, $clientId . \":\" . $clientSecret);\n\n$response = curl_exec($ch);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL, $response, PHP_EOL;\ncurl_close($ch);\n"
          },
          {
            "lang": "JavaScript",
            "label": "Node.js",
            "source": "const auth = Buffer.from(`${clientId}:${clientSecret}`).toString(\"base64\");\n\nconst response = await fetch(\"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/balance\", {\n  method: \"GET\",\n  headers: {\n    Authorization: `Basic ${auth}`,\n  },\n});\n\nconsole.log(response.status, await response.json());\n"
          }
        ]
      }
    },
    "/baas/v1/account/{account_id}/pix/keys": {
      "get": {
        "tags": [
          "PIX keys"
        ],
        "summary": "List PIX keys",
        "description": "Every PIX key registered to the account.\n\nThis endpoint does **not** paginate — `meta` carries only a total.",
        "operationId": "getPixKeys",
        "security": [
          {
            "TokenBasic": []
          }
        ],
        "parameters": [
          {
            "name": "account_id",
            "in": "path",
            "required": true,
            "description": "The ZAPPY account this call acts on. Must be a UUID your credential is scoped to.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77"
          }
        ],
        "responses": {
          "200": {
            "description": "The account's PIX keys.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PixKeysResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed, or the account is not active and verified.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.ACC.003",
                  "message": "Account is not verified",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, or non-Basic credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.AUT.009",
                  "message": "Basic authorization is required",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required permission, or is scoped to another account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.AUT.010",
                  "message": "You are not authorized to access this resource",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "404": {
            "description": "Account not found, or not visible to this credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.ACC.001",
                  "message": "Account not found",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "502": {
            "description": "The provider could not be reached.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.PIX.002",
                  "message": "Failed to retrieve PIX keys",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "503": {
            "description": "The authentication service is unavailable. Retry with backoff.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.SYS.002",
                  "message": "Authentication service is unavailable",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "cURL",
            "source": "curl -sS -X GET \"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/pix/keys\" \\\n  -u \"$CLIENT_ID:$CLIENT_SECRET\"\n"
          },
          {
            "lang": "Go",
            "label": "Go",
            "source": "package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/pix/keys\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.SetBasicAuth(clientID, clientSecret)\n\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\n\tpayload, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.StatusCode, string(payload))\n}\n"
          },
          {
            "lang": "PHP",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init(\"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/pix/keys\");\ncurl_setopt($ch, CURLOPT_CUSTOMREQUEST, \"GET\");\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_setopt($ch, CURLOPT_USERPWD, $clientId . \":\" . $clientSecret);\n\n$response = curl_exec($ch);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL, $response, PHP_EOL;\ncurl_close($ch);\n"
          },
          {
            "lang": "JavaScript",
            "label": "Node.js",
            "source": "const auth = Buffer.from(`${clientId}:${clientSecret}`).toString(\"base64\");\n\nconst response = await fetch(\"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/pix/keys\", {\n  method: \"GET\",\n  headers: {\n    Authorization: `Basic ${auth}`,\n  },\n});\n\nconsole.log(response.status, await response.json());\n"
          }
        ]
      }
    },
    "/baas/v1/account/{account_id}/pix/keys/{key_id}": {
      "get": {
        "tags": [
          "PIX keys"
        ],
        "summary": "Get a PIX key",
        "description": "One PIX key by its identifier. Returns the key on its own, not wrapped in a `data` envelope.",
        "operationId": "getPixKey",
        "security": [
          {
            "TokenBasic": []
          }
        ],
        "parameters": [
          {
            "name": "account_id",
            "in": "path",
            "required": true,
            "description": "The ZAPPY account this call acts on. Must be a UUID your credential is scoped to.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77"
          },
          {
            "name": "key_id",
            "in": "path",
            "required": true,
            "description": "The key's UUID, as returned by the list endpoint.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "2f315c7c-1a0b-4d2e-9d9e-9a1b0f9c2c9e"
          }
        ],
        "responses": {
          "200": {
            "description": "The PIX key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PixKeyItem"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed, or the account is not active and verified.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.ACC.003",
                  "message": "Account is not verified",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, or non-Basic credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.AUT.009",
                  "message": "Basic authorization is required",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required permission, or is scoped to another account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.AUT.010",
                  "message": "You are not authorized to access this resource",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "404": {
            "description": "Account not found, or not visible to this credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.ACC.001",
                  "message": "Account not found",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "502": {
            "description": "The provider could not be reached.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.PIX.002",
                  "message": "Failed to retrieve PIX key",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "503": {
            "description": "The authentication service is unavailable. Retry with backoff.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.SYS.002",
                  "message": "Authentication service is unavailable",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "cURL",
            "source": "curl -sS -X GET \"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/pix/keys/2f315c7c-1a0b-4d2e-9d9e-9a1b0f9c2c9e\" \\\n  -u \"$CLIENT_ID:$CLIENT_SECRET\"\n"
          },
          {
            "lang": "Go",
            "label": "Go",
            "source": "package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/pix/keys/2f315c7c-1a0b-4d2e-9d9e-9a1b0f9c2c9e\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.SetBasicAuth(clientID, clientSecret)\n\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\n\tpayload, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.StatusCode, string(payload))\n}\n"
          },
          {
            "lang": "PHP",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init(\"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/pix/keys/2f315c7c-1a0b-4d2e-9d9e-9a1b0f9c2c9e\");\ncurl_setopt($ch, CURLOPT_CUSTOMREQUEST, \"GET\");\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_setopt($ch, CURLOPT_USERPWD, $clientId . \":\" . $clientSecret);\n\n$response = curl_exec($ch);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL, $response, PHP_EOL;\ncurl_close($ch);\n"
          },
          {
            "lang": "JavaScript",
            "label": "Node.js",
            "source": "const auth = Buffer.from(`${clientId}:${clientSecret}`).toString(\"base64\");\n\nconst response = await fetch(\"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/pix/keys/2f315c7c-1a0b-4d2e-9d9e-9a1b0f9c2c9e\", {\n  method: \"GET\",\n  headers: {\n    Authorization: `Basic ${auth}`,\n  },\n});\n\nconsole.log(response.status, await response.json());\n"
          }
        ]
      }
    },
    "/baas/v1/account/{account_id}/pix/qrcode/{reference}": {
      "get": {
        "tags": [
          "PIX QR codes"
        ],
        "summary": "Get a PIX QR code",
        "description": "The charge behind a reference.\n\n`qrcode.hash` is the EMV copy-and-paste payload — render it as a QR image or offer it as text. Honour `expires_at`: an expired charge cannot be paid.\n\n`id`, `name` and `description` are empty on this endpoint.",
        "operationId": "getPixQRCode",
        "security": [
          {
            "TokenBasic": []
          }
        ],
        "parameters": [
          {
            "name": "account_id",
            "in": "path",
            "required": true,
            "description": "The ZAPPY account this call acts on. Must be a UUID your credential is scoped to.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77"
          },
          {
            "name": "reference",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The charge reference.",
            "example": "charge-10492"
          }
        ],
        "responses": {
          "200": {
            "description": "The charge.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PixQRCodeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed, or the account is not active and verified.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.ACC.003",
                  "message": "Account is not verified",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, or non-Basic credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.AUT.009",
                  "message": "Basic authorization is required",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required permission, or is scoped to another account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.AUT.010",
                  "message": "You are not authorized to access this resource",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "404": {
            "description": "Account not found, or not visible to this credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.ACC.001",
                  "message": "Account not found",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "502": {
            "description": "The provider could not be reached.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.PIX.005",
                  "message": "Failed to retrieve PIX QR code",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "503": {
            "description": "The authentication service is unavailable. Retry with backoff.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.SYS.002",
                  "message": "Authentication service is unavailable",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "cURL",
            "source": "curl -sS -X GET \"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/pix/qrcode/charge-10492\" \\\n  -u \"$CLIENT_ID:$CLIENT_SECRET\"\n"
          },
          {
            "lang": "Go",
            "label": "Go",
            "source": "package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/pix/qrcode/charge-10492\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.SetBasicAuth(clientID, clientSecret)\n\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\n\tpayload, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.StatusCode, string(payload))\n}\n"
          },
          {
            "lang": "PHP",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init(\"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/pix/qrcode/charge-10492\");\ncurl_setopt($ch, CURLOPT_CUSTOMREQUEST, \"GET\");\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_setopt($ch, CURLOPT_USERPWD, $clientId . \":\" . $clientSecret);\n\n$response = curl_exec($ch);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL, $response, PHP_EOL;\ncurl_close($ch);\n"
          },
          {
            "lang": "JavaScript",
            "label": "Node.js",
            "source": "const auth = Buffer.from(`${clientId}:${clientSecret}`).toString(\"base64\");\n\nconst response = await fetch(\"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/pix/qrcode/charge-10492\", {\n  method: \"GET\",\n  headers: {\n    Authorization: `Basic ${auth}`,\n  },\n});\n\nconsole.log(response.status, await response.json());\n"
          }
        ]
      }
    },
    "/baas/v1/account/{account_id}/pix/transactions/{reference}": {
      "get": {
        "tags": [
          "PIX transactions"
        ],
        "summary": "Get a PIX transaction",
        "description": "Resolves a charge reference to its payment: `paid_at`, the Central Bank `e2e_id`, and the `payer`.\n\nWhile the charge is still unpaid this returns the charge in a pending state rather than a `404`, so a poll loop does not have to treat not-found as an error. An anonymous charge has no `payer` block.",
        "operationId": "getPixTransaction",
        "security": [
          {
            "TokenBasic": []
          }
        ],
        "parameters": [
          {
            "name": "account_id",
            "in": "path",
            "required": true,
            "description": "The ZAPPY account this call acts on. Must be a UUID your credential is scoped to.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77"
          },
          {
            "name": "reference",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The charge reference.",
            "example": "charge-10492"
          }
        ],
        "responses": {
          "200": {
            "description": "The transaction, settled or still pending.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PixTransaction"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed, or the account is not active and verified.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.ACC.003",
                  "message": "Account is not verified",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, or non-Basic credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.AUT.009",
                  "message": "Basic authorization is required",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required permission, or is scoped to another account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.AUT.010",
                  "message": "You are not authorized to access this resource",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "404": {
            "description": "Account not found, or not visible to this credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.ACC.001",
                  "message": "Account not found",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "502": {
            "description": "The provider could not be reached.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.PIX.007",
                  "message": "Failed to retrieve PIX transaction",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "503": {
            "description": "The authentication service is unavailable. Retry with backoff.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.SYS.002",
                  "message": "Authentication service is unavailable",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "cURL",
            "source": "curl -sS -X GET \"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/pix/transactions/charge-10492\" \\\n  -u \"$CLIENT_ID:$CLIENT_SECRET\"\n"
          },
          {
            "lang": "Go",
            "label": "Go",
            "source": "package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/pix/transactions/charge-10492\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.SetBasicAuth(clientID, clientSecret)\n\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\n\tpayload, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.StatusCode, string(payload))\n}\n"
          },
          {
            "lang": "PHP",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init(\"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/pix/transactions/charge-10492\");\ncurl_setopt($ch, CURLOPT_CUSTOMREQUEST, \"GET\");\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_setopt($ch, CURLOPT_USERPWD, $clientId . \":\" . $clientSecret);\n\n$response = curl_exec($ch);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL, $response, PHP_EOL;\ncurl_close($ch);\n"
          },
          {
            "lang": "JavaScript",
            "label": "Node.js",
            "source": "const auth = Buffer.from(`${clientId}:${clientSecret}`).toString(\"base64\");\n\nconst response = await fetch(\"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/pix/transactions/charge-10492\", {\n  method: \"GET\",\n  headers: {\n    Authorization: `Basic ${auth}`,\n  },\n});\n\nconsole.log(response.status, await response.json());\n"
          }
        ]
      }
    },
    "/baas/v1/account/{account_id}/transactions": {
      "get": {
        "tags": [
          "Accounts"
        ],
        "summary": "List statement entries",
        "description": "The account statement for a date window, newest first, alongside the balance and the account's own bank coordinates.\n\n`init` and `ends` are **required**, inclusive, and may not span more than 90 days. Each entry's `operation` is `Pix In` or `Pix Out`, and `tags` carries the provider identifier and the end-to-end identifier when the provider supplied them.",
        "operationId": "getAccountTransactions",
        "security": [
          {
            "TokenBasic": []
          }
        ],
        "parameters": [
          {
            "name": "account_id",
            "in": "path",
            "required": true,
            "description": "The ZAPPY account this call acts on. Must be a UUID your credential is scoped to.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77"
          },
          {
            "name": "init",
            "in": "query",
            "required": true,
            "description": "Window start, inclusive. `YYYY-MM-DD`.",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-09-01"
          },
          {
            "name": "ends",
            "in": "query",
            "required": true,
            "description": "Window end, inclusive. Must not precede `init`, and the window may not exceed 90 days.",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-09-22"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "1-based page number.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            },
            "example": 1
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Values above 100 are silently clamped to 100; values below 1 are rejected.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            },
            "example": 25
          }
        ],
        "responses": {
          "200": {
            "description": "A page of statement entries.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountTransactionsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed, or the account is not active and verified.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.ACC.003",
                  "message": "Account is not verified",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, or non-Basic credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.AUT.009",
                  "message": "Basic authorization is required",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required permission, or is scoped to another account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.AUT.010",
                  "message": "You are not authorized to access this resource",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "404": {
            "description": "Account not found, or not visible to this credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.ACC.001",
                  "message": "Account not found",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "502": {
            "description": "The provider could not be reached.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.ACC.007",
                  "message": "Failed to retrieve account transactions",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "503": {
            "description": "The authentication service is unavailable. Retry with backoff.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.SYS.002",
                  "message": "Authentication service is unavailable",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "cURL",
            "source": "curl -sS -X GET \"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/transactions?init=2026-09-01&ends=2026-09-22\" \\\n  -u \"$CLIENT_ID:$CLIENT_SECRET\"\n"
          },
          {
            "lang": "Go",
            "label": "Go",
            "source": "package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/transactions?init=2026-09-01&ends=2026-09-22\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.SetBasicAuth(clientID, clientSecret)\n\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\n\tpayload, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.StatusCode, string(payload))\n}\n"
          },
          {
            "lang": "PHP",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init(\"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/transactions?init=2026-09-01&ends=2026-09-22\");\ncurl_setopt($ch, CURLOPT_CUSTOMREQUEST, \"GET\");\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_setopt($ch, CURLOPT_USERPWD, $clientId . \":\" . $clientSecret);\n\n$response = curl_exec($ch);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL, $response, PHP_EOL;\ncurl_close($ch);\n"
          },
          {
            "lang": "JavaScript",
            "label": "Node.js",
            "source": "const auth = Buffer.from(`${clientId}:${clientSecret}`).toString(\"base64\");\n\nconst response = await fetch(\"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/transactions?init=2026-09-01&ends=2026-09-22\", {\n  method: \"GET\",\n  headers: {\n    Authorization: `Basic ${auth}`,\n  },\n});\n\nconsole.log(response.status, await response.json());\n"
          }
        ]
      }
    },
    "/baas/v1/account/{account_id}/withdraw": {
      "post": {
        "tags": [
          "Payouts"
        ],
        "summary": "Create a payout",
        "description": "Moves money out of the account, to a PIX key (`method: pix`) or to a bank account (`method: bank_account`).\n\nThree rules catch most first integrations:\n\n- `reference` is **yours**, must be unique and stable, and is the only way to look the payout up afterwards. Reuse it on a retry so a lost response cannot become a double payment.\n- `date` must be **today in UTC**. Scheduled payouts are rejected.\n- `method: qrcode` is not supported and is rejected with `ZPY.PIX.012`.\n\nThe response is always `status: \"processing\"` — acceptance, not settlement. Poll `GET /withdraw/{reference}` to watch it advance.",
        "operationId": "createWithdraw",
        "security": [
          {
            "TokenBasic": []
          }
        ],
        "parameters": [
          {
            "name": "account_id",
            "in": "path",
            "required": true,
            "description": "The ZAPPY account this call acts on. Must be a UUID your credential is scoped to.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77"
          }
        ],
        "responses": {
          "200": {
            "description": "The payout was accepted for processing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WithdrawResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed, or the account is not active and verified.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.ACC.003",
                  "message": "Account is not verified",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, or non-Basic credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.AUT.009",
                  "message": "Basic authorization is required",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required permission, or is scoped to another account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.AUT.010",
                  "message": "You are not authorized to access this resource",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "404": {
            "description": "Account not found, or not visible to this credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.ACC.001",
                  "message": "Account not found",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "422": {
            "description": "No banking provider is configured for this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.ACC.005",
                  "message": "No banking provider is configured for this account",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "500": {
            "description": "The payout intent could not be persisted. Do not retry blindly — look the reference up first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.SYS.001",
                  "message": "Failed to persist withdrawal intent",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "502": {
            "description": "The provider rejected or could not process the payout.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.PIX.010",
                  "message": "Failed to process withdrawal",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "503": {
            "description": "The authentication service is unavailable. Retry with backoff.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.SYS.002",
                  "message": "Authentication service is unavailable",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WithdrawRequest"
              },
              "example": {
                "method": "pix",
                "reference": "payout-2026-09-22-0001",
                "destination": {
                  "name": "Carlos Pereira",
                  "tax_number": "123.456.789-09"
                },
                "pix": {
                  "type": "email",
                  "key": "carlos.pereira@exemplo.com.br"
                },
                "description": "Repasse semanal",
                "message": "Obrigado!",
                "date": "2026-09-22",
                "value": 250.0
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "cURL",
            "source": "curl -sS -X POST \"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/withdraw\" \\\n  -u \"$CLIENT_ID:$CLIENT_SECRET\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"method\":\"pix\",\"reference\":\"payout-2026-09-22-0001\",\"destination\":{\"name\":\"Carlos Pereira\",\"tax_number\":\"123.456.789-09\"},\"pix\":{\"type\":\"email\",\"key\":\"carlos.pereira@exemplo.com.br\"},\"description\":\"Repasse semanal\",\"message\":\"Obrigado!\",\"date\":\"2026-09-22\",\"value\":250.0}'\n"
          },
          {
            "lang": "Go",
            "label": "Go",
            "source": "package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := `{\n\t  \"method\": \"pix\",\n\t  \"reference\": \"payout-2026-09-22-0001\",\n\t  \"destination\": {\n\t    \"name\": \"Carlos Pereira\",\n\t    \"tax_number\": \"123.456.789-09\"\n\t  },\n\t  \"pix\": {\n\t    \"type\": \"email\",\n\t    \"key\": \"carlos.pereira@exemplo.com.br\"\n\t  },\n\t  \"description\": \"Repasse semanal\",\n\t  \"message\": \"Obrigado!\",\n\t  \"date\": \"2026-09-22\",\n\t  \"value\": 250.0\n\t}`\n\n\treq, err := http.NewRequest(\"POST\", \"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/withdraw\", strings.NewReader(body))\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.SetBasicAuth(clientID, clientSecret)\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\n\tpayload, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.StatusCode, string(payload))\n}\n"
          },
          {
            "lang": "PHP",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init(\"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/withdraw\");\ncurl_setopt($ch, CURLOPT_CUSTOMREQUEST, \"POST\");\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_setopt($ch, CURLOPT_USERPWD, $clientId . \":\" . $clientSecret);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, [\"Content-Type: application/json\"]);\n\n$payload = <<<'JSON'\n{\n  \"method\": \"pix\",\n  \"reference\": \"payout-2026-09-22-0001\",\n  \"destination\": {\n    \"name\": \"Carlos Pereira\",\n    \"tax_number\": \"123.456.789-09\"\n  },\n  \"pix\": {\n    \"type\": \"email\",\n    \"key\": \"carlos.pereira@exemplo.com.br\"\n  },\n  \"description\": \"Repasse semanal\",\n  \"message\": \"Obrigado!\",\n  \"date\": \"2026-09-22\",\n  \"value\": 250.0\n}\nJSON;\n\ncurl_setopt($ch, CURLOPT_POSTFIELDS, $payload);\n\n$response = curl_exec($ch);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL, $response, PHP_EOL;\ncurl_close($ch);\n"
          },
          {
            "lang": "JavaScript",
            "label": "Node.js",
            "source": "const auth = Buffer.from(`${clientId}:${clientSecret}`).toString(\"base64\");\n\nconst response = await fetch(\"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/withdraw\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Basic ${auth}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"method\": \"pix\",\n    \"reference\": \"payout-2026-09-22-0001\",\n    \"destination\": {\n      \"name\": \"Carlos Pereira\",\n      \"tax_number\": \"123.456.789-09\"\n    },\n    \"pix\": {\n      \"type\": \"email\",\n      \"key\": \"carlos.pereira@exemplo.com.br\"\n    },\n    \"description\": \"Repasse semanal\",\n    \"message\": \"Obrigado!\",\n    \"date\": \"2026-09-22\",\n    \"value\": 250.0\n  }),\n});\n\nconsole.log(response.status, await response.json());\n"
          }
        ]
      }
    },
    "/baas/v1/account/{account_id}/withdraw/{reference}": {
      "get": {
        "tags": [
          "Payouts"
        ],
        "summary": "Get a payout",
        "description": "Looks a payout up by the `reference` you supplied when creating it, and returns its current settlement status, both parties, and the end-to-end identifier once settled.",
        "operationId": "getWithdraw",
        "security": [
          {
            "TokenBasic": []
          }
        ],
        "parameters": [
          {
            "name": "account_id",
            "in": "path",
            "required": true,
            "description": "The ZAPPY account this call acts on. Must be a UUID your credential is scoped to.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77"
          },
          {
            "name": "reference",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The `reference` you supplied when creating the payout.",
            "example": "payout-2026-09-22-0001"
          }
        ],
        "responses": {
          "200": {
            "description": "The payout.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetWithdrawResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed, or the account is not active and verified.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.ACC.003",
                  "message": "Account is not verified",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, or non-Basic credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.AUT.009",
                  "message": "Basic authorization is required",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required permission, or is scoped to another account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.AUT.010",
                  "message": "You are not authorized to access this resource",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "404": {
            "description": "Account not found, or not visible to this credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.ACC.001",
                  "message": "Account not found",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "502": {
            "description": "The provider could not be reached.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.PIX.010",
                  "message": "Failed to retrieve withdrawal",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "503": {
            "description": "The authentication service is unavailable. Retry with backoff.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.SYS.002",
                  "message": "Authentication service is unavailable",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "cURL",
            "source": "curl -sS -X GET \"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/withdraw/payout-2026-09-22-0001\" \\\n  -u \"$CLIENT_ID:$CLIENT_SECRET\"\n"
          },
          {
            "lang": "Go",
            "label": "Go",
            "source": "package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/withdraw/payout-2026-09-22-0001\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.SetBasicAuth(clientID, clientSecret)\n\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\n\tpayload, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.StatusCode, string(payload))\n}\n"
          },
          {
            "lang": "PHP",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init(\"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/withdraw/payout-2026-09-22-0001\");\ncurl_setopt($ch, CURLOPT_CUSTOMREQUEST, \"GET\");\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_setopt($ch, CURLOPT_USERPWD, $clientId . \":\" . $clientSecret);\n\n$response = curl_exec($ch);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL, $response, PHP_EOL;\ncurl_close($ch);\n"
          },
          {
            "lang": "JavaScript",
            "label": "Node.js",
            "source": "const auth = Buffer.from(`${clientId}:${clientSecret}`).toString(\"base64\");\n\nconst response = await fetch(\"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/withdraw/payout-2026-09-22-0001\", {\n  method: \"GET\",\n  headers: {\n    Authorization: `Basic ${auth}`,\n  },\n});\n\nconsole.log(response.status, await response.json());\n"
          }
        ]
      },
      "delete": {
        "tags": [
          "Payouts"
        ],
        "summary": "Cancel a payout (not implemented)",
        "description": "**This endpoint is not implemented and always returns `501`.**\n\nIt is documented because it exists in the route table and will answer a request. There is no way to cancel a submitted payout through this API today — treat a payout as final once accepted.",
        "operationId": "cancelWithdraw",
        "deprecated": true,
        "security": [
          {
            "TokenBasic": []
          }
        ],
        "parameters": [
          {
            "name": "account_id",
            "in": "path",
            "required": true,
            "description": "The ZAPPY account this call acts on. Must be a UUID your credential is scoped to.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77"
          },
          {
            "name": "reference",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "payout-2026-09-22-0001"
          }
        ],
        "responses": {
          "501": {
            "description": "Always. Cancellation is not implemented.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.PIX.018",
                  "message": "Withdrawal cancellation is not implemented",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "cURL",
            "source": "curl -sS -X DELETE \"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/withdraw/payout-2026-09-22-0001\" \\\n  -u \"$CLIENT_ID:$CLIENT_SECRET\"\n"
          },
          {
            "lang": "Go",
            "label": "Go",
            "source": "package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"DELETE\", \"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/withdraw/payout-2026-09-22-0001\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.SetBasicAuth(clientID, clientSecret)\n\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\n\tpayload, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.StatusCode, string(payload))\n}\n"
          },
          {
            "lang": "PHP",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init(\"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/withdraw/payout-2026-09-22-0001\");\ncurl_setopt($ch, CURLOPT_CUSTOMREQUEST, \"DELETE\");\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_setopt($ch, CURLOPT_USERPWD, $clientId . \":\" . $clientSecret);\n\n$response = curl_exec($ch);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL, $response, PHP_EOL;\ncurl_close($ch);\n"
          },
          {
            "lang": "JavaScript",
            "label": "Node.js",
            "source": "const auth = Buffer.from(`${clientId}:${clientSecret}`).toString(\"base64\");\n\nconst response = await fetch(\"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/withdraw/payout-2026-09-22-0001\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: `Basic ${auth}`,\n  },\n});\n\nconsole.log(response.status, await response.json());\n"
          }
        ]
      }
    },
    "/baas/v1/account/{account_id}/withdraws": {
      "get": {
        "tags": [
          "Payouts"
        ],
        "summary": "List payouts",
        "description": "Payouts created in a date window. Same window rules as the statement: `init` and `ends` are required, inclusive, and capped at 90 days.",
        "operationId": "getWithdraws",
        "security": [
          {
            "TokenBasic": []
          }
        ],
        "parameters": [
          {
            "name": "account_id",
            "in": "path",
            "required": true,
            "description": "The ZAPPY account this call acts on. Must be a UUID your credential is scoped to.",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77"
          },
          {
            "name": "init",
            "in": "query",
            "required": true,
            "description": "Window start, inclusive. `YYYY-MM-DD`.",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-09-01"
          },
          {
            "name": "ends",
            "in": "query",
            "required": true,
            "description": "Window end, inclusive. Must not precede `init`, and the window may not exceed 90 days.",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-09-22"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "1-based page number.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            },
            "example": 1
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size. Values above 100 are silently clamped to 100; values below 1 are rejected.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            },
            "example": 25
          }
        ],
        "responses": {
          "200": {
            "description": "A page of payouts.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WithdrawsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation failed, or the account is not active and verified.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.ACC.003",
                  "message": "Account is not verified",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, or non-Basic credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.AUT.009",
                  "message": "Basic authorization is required",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "403": {
            "description": "The credential lacks the required permission, or is scoped to another account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.AUT.010",
                  "message": "You are not authorized to access this resource",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "404": {
            "description": "Account not found, or not visible to this credential.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.ACC.001",
                  "message": "Account not found",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "502": {
            "description": "The provider could not be reached.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.PIX.010",
                  "message": "Failed to retrieve withdrawals",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "503": {
            "description": "The authentication service is unavailable. Retry with backoff.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "ZPY.SYS.002",
                  "message": "Authentication service is unavailable",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "cURL",
            "source": "curl -sS -X GET \"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/withdraws?init=2026-09-01&ends=2026-09-22\" \\\n  -u \"$CLIENT_ID:$CLIENT_SECRET\"\n"
          },
          {
            "lang": "Go",
            "label": "Go",
            "source": "package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"GET\", \"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/withdraws?init=2026-09-01&ends=2026-09-22\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.SetBasicAuth(clientID, clientSecret)\n\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\n\tpayload, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.StatusCode, string(payload))\n}\n"
          },
          {
            "lang": "PHP",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init(\"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/withdraws?init=2026-09-01&ends=2026-09-22\");\ncurl_setopt($ch, CURLOPT_CUSTOMREQUEST, \"GET\");\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_setopt($ch, CURLOPT_USERPWD, $clientId . \":\" . $clientSecret);\n\n$response = curl_exec($ch);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL, $response, PHP_EOL;\ncurl_close($ch);\n"
          },
          {
            "lang": "JavaScript",
            "label": "Node.js",
            "source": "const auth = Buffer.from(`${clientId}:${clientSecret}`).toString(\"base64\");\n\nconst response = await fetch(\"https://api.sdx.zappy.com.br/baas/v1/account/019a2094-4c6d-7a31-9f0e-2b8c5d1e4a77/withdraws?init=2026-09-01&ends=2026-09-22\", {\n  method: \"GET\",\n  headers: {\n    Authorization: `Basic ${auth}`,\n  },\n});\n\nconsole.log(response.status, await response.json());\n"
          }
        ]
      }
    },
    "/iam/v1/auth/forgot-password": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Request a password reset",
        "description": "Sends a reset link when the address belongs to an account.\n\nThe response is **always** the same whether or not the address exists — the endpoint deliberately does not let a caller enumerate users.",
        "operationId": "forgotPassword",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ForgotPasswordRequest"
              },
              "example": {
                "email": "ana.souza@empresa.com.br"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted. Identical whether or not the address exists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessageResponse"
                },
                "example": {
                  "message": "if the email exists, a reset link will be sent"
                }
              }
            }
          },
          "400": {
            "description": "The payload failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "VALIDATION_FAILED",
                  "message": "request validation failed",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "cURL",
            "source": "curl -sS -X POST \"https://api.sdx.zappy.com.br/iam/v1/auth/forgot-password\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"email\":\"ana.souza@empresa.com.br\"}'\n"
          },
          {
            "lang": "Go",
            "label": "Go",
            "source": "package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := `{\n\t  \"email\": \"ana.souza@empresa.com.br\"\n\t}`\n\n\treq, err := http.NewRequest(\"POST\", \"https://api.sdx.zappy.com.br/iam/v1/auth/forgot-password\", strings.NewReader(body))\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\n\tpayload, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.StatusCode, string(payload))\n}\n"
          },
          {
            "lang": "PHP",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init(\"https://api.sdx.zappy.com.br/iam/v1/auth/forgot-password\");\ncurl_setopt($ch, CURLOPT_CUSTOMREQUEST, \"POST\");\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, [\"Content-Type: application/json\"]);\n\n$payload = <<<'JSON'\n{\n  \"email\": \"ana.souza@empresa.com.br\"\n}\nJSON;\n\ncurl_setopt($ch, CURLOPT_POSTFIELDS, $payload);\n\n$response = curl_exec($ch);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL, $response, PHP_EOL;\ncurl_close($ch);\n"
          },
          {
            "lang": "JavaScript",
            "label": "Node.js",
            "source": "const response = await fetch(\"https://api.sdx.zappy.com.br/iam/v1/auth/forgot-password\", {\n  method: \"POST\",\n  headers: {\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"email\": \"ana.souza@empresa.com.br\"\n  }),\n});\n\nconsole.log(response.status, await response.json());\n"
          }
        ]
      }
    },
    "/iam/v1/auth/login": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Sign in",
        "description": "Exchanges an e-mail and password for a session.\n\nWhen the user has a second factor enrolled the response carries **only** `mfa_required` and `mfa_token` — no name, e-mail or roles, because a challenge must not confirm that an account exists. Present the challenge at `POST /iam/v1/auth/mfa`.\n\nRepeated failures are rate limited; a `429` carries a `Retry-After` header in seconds.",
        "operationId": "login",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoginRequest"
              },
              "example": {
                "username": "ana.souza@empresa.com.br",
                "password": "correct-horse-battery"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A full session, or a pending second-factor challenge.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LoginResponse"
                },
                "examples": {
                  "session": {
                    "summary": "Signed in",
                    "value": {
                      "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
                      "refresh_token": "e3b0c44298fc1c149afbf4c8996fb924",
                      "type": "Bearer",
                      "expires_at": 1790082011,
                      "user": {
                        "id": "8f14e45f-ceea-467a-9f1f-9b2a5d6f3c11",
                        "name": "Ana Souza",
                        "email": "ana.souza@empresa.com.br",
                        "roles": [
                          "company_admin"
                        ]
                      }
                    }
                  },
                  "mfa": {
                    "summary": "Second factor required",
                    "value": {
                      "mfa_required": true,
                      "mfa_token": "c7f1a0b2f3149afbf4c8996fb9241a1b"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The payload failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "VALIDATION_FAILED",
                  "message": "request validation failed",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "401": {
            "description": "Wrong e-mail or password.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "INVALID_CREDENTIALS",
                  "message": "invalid email or password",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "403": {
            "description": "The account is blocked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "USER_BLOCKED",
                  "message": "user account is blocked",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "429": {
            "description": "Too many attempts. Wait for `Retry-After` seconds.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "RATE_LIMITED",
                  "message": "too many login attempts"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "cURL",
            "source": "curl -sS -X POST \"https://api.sdx.zappy.com.br/iam/v1/auth/login\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"username\":\"ana.souza@empresa.com.br\",\"password\":\"correct-horse-battery\"}'\n"
          },
          {
            "lang": "Go",
            "label": "Go",
            "source": "package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := `{\n\t  \"username\": \"ana.souza@empresa.com.br\",\n\t  \"password\": \"correct-horse-battery\"\n\t}`\n\n\treq, err := http.NewRequest(\"POST\", \"https://api.sdx.zappy.com.br/iam/v1/auth/login\", strings.NewReader(body))\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\n\tpayload, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.StatusCode, string(payload))\n}\n"
          },
          {
            "lang": "PHP",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init(\"https://api.sdx.zappy.com.br/iam/v1/auth/login\");\ncurl_setopt($ch, CURLOPT_CUSTOMREQUEST, \"POST\");\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, [\"Content-Type: application/json\"]);\n\n$payload = <<<'JSON'\n{\n  \"username\": \"ana.souza@empresa.com.br\",\n  \"password\": \"correct-horse-battery\"\n}\nJSON;\n\ncurl_setopt($ch, CURLOPT_POSTFIELDS, $payload);\n\n$response = curl_exec($ch);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL, $response, PHP_EOL;\ncurl_close($ch);\n"
          },
          {
            "lang": "JavaScript",
            "label": "Node.js",
            "source": "const response = await fetch(\"https://api.sdx.zappy.com.br/iam/v1/auth/login\", {\n  method: \"POST\",\n  headers: {\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"username\": \"ana.souza@empresa.com.br\",\n    \"password\": \"correct-horse-battery\"\n  }),\n});\n\nconsole.log(response.status, await response.json());\n"
          }
        ]
      }
    },
    "/iam/v1/auth/logout": {
      "delete": {
        "tags": [
          "Authentication"
        ],
        "summary": "Sign out",
        "description": "Revokes the current session. The only identity endpoint that requires a bearer token.\n\nNote the method is `DELETE`, not `POST`. A Basic credential is rejected here.",
        "operationId": "logout",
        "security": [
          {
            "UserBearer": []
          }
        ],
        "responses": {
          "204": {
            "description": "The session is revoked. No body."
          },
          "401": {
            "description": "Missing, invalid, or non-user credentials, or the session is already revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "INVALID_CREDENTIALS",
                  "message": "user credentials required",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "cURL",
            "source": "curl -sS -X DELETE \"https://api.sdx.zappy.com.br/iam/v1/auth/logout\" \\\n  -H \"Authorization: Bearer $ACCESS_TOKEN\"\n"
          },
          {
            "lang": "Go",
            "label": "Go",
            "source": "package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n)\n\nfunc main() {\n\treq, err := http.NewRequest(\"DELETE\", \"https://api.sdx.zappy.com.br/iam/v1/auth/logout\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Authorization\", \"Bearer \"+accessToken)\n\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\n\tpayload, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.StatusCode, string(payload))\n}\n"
          },
          {
            "lang": "PHP",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init(\"https://api.sdx.zappy.com.br/iam/v1/auth/logout\");\ncurl_setopt($ch, CURLOPT_CUSTOMREQUEST, \"DELETE\");\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, [\"Authorization: Bearer \" . $accessToken]);\n\n$response = curl_exec($ch);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL, $response, PHP_EOL;\ncurl_close($ch);\n"
          },
          {
            "lang": "JavaScript",
            "label": "Node.js",
            "source": "const response = await fetch(\"https://api.sdx.zappy.com.br/iam/v1/auth/logout\", {\n  method: \"DELETE\",\n  headers: {\n    Authorization: `Bearer ${accessToken}`,\n  },\n});\n\nconsole.log(response.status, await response.json());\n"
          }
        ]
      }
    },
    "/iam/v1/auth/mfa": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Verify the second factor",
        "description": "Second step of sign-in. Public because the caller holds no bearer token yet — the `mfa_token` from login is the only thing authorising it.\n\nAccepts a six-digit authenticator code or a recovery code. A code cannot be replayed.",
        "operationId": "verifyMfa",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MFAVerifyRequest"
              },
              "example": {
                "mfa_token": "c7f1a0b2f3149afbf4c8996fb9241a1b",
                "code": "418902"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The session, now fully authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LoginResponse"
                }
              }
            }
          },
          "400": {
            "description": "The payload failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "VALIDATION_FAILED",
                  "message": "request validation failed",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or expired challenge, wrong code, a reused code, or no factor enrolled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "MFA_INVALID_CODE",
                  "message": "invalid code",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "403": {
            "description": "The account is blocked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "USER_BLOCKED",
                  "message": "user account is blocked",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "429": {
            "description": "Too many attempts. Wait for `Retry-After` seconds.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "RATE_LIMITED",
                  "message": "too many verification attempts"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "cURL",
            "source": "curl -sS -X POST \"https://api.sdx.zappy.com.br/iam/v1/auth/mfa\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"mfa_token\":\"c7f1a0b2f3149afbf4c8996fb9241a1b\",\"code\":\"418902\"}'\n"
          },
          {
            "lang": "Go",
            "label": "Go",
            "source": "package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := `{\n\t  \"mfa_token\": \"c7f1a0b2f3149afbf4c8996fb9241a1b\",\n\t  \"code\": \"418902\"\n\t}`\n\n\treq, err := http.NewRequest(\"POST\", \"https://api.sdx.zappy.com.br/iam/v1/auth/mfa\", strings.NewReader(body))\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\n\tpayload, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.StatusCode, string(payload))\n}\n"
          },
          {
            "lang": "PHP",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init(\"https://api.sdx.zappy.com.br/iam/v1/auth/mfa\");\ncurl_setopt($ch, CURLOPT_CUSTOMREQUEST, \"POST\");\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, [\"Content-Type: application/json\"]);\n\n$payload = <<<'JSON'\n{\n  \"mfa_token\": \"c7f1a0b2f3149afbf4c8996fb9241a1b\",\n  \"code\": \"418902\"\n}\nJSON;\n\ncurl_setopt($ch, CURLOPT_POSTFIELDS, $payload);\n\n$response = curl_exec($ch);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL, $response, PHP_EOL;\ncurl_close($ch);\n"
          },
          {
            "lang": "JavaScript",
            "label": "Node.js",
            "source": "const response = await fetch(\"https://api.sdx.zappy.com.br/iam/v1/auth/mfa\", {\n  method: \"POST\",\n  headers: {\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"mfa_token\": \"c7f1a0b2f3149afbf4c8996fb9241a1b\",\n    \"code\": \"418902\"\n  }),\n});\n\nconsole.log(response.status, await response.json());\n"
          }
        ]
      }
    },
    "/iam/v1/auth/refresh": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Rotate the session",
        "description": "Exchanges a refresh token for a new access and refresh pair.\n\n**Rotation is destructive**: the presented refresh token is revoked and the old session replaced. A refresh token is single-use, so never refresh concurrently for one session — the loser gets a `401` and the user is signed out.",
        "operationId": "refreshSession",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RefreshRequest"
              },
              "example": {
                "refresh_token": "e3b0c44298fc1c149afbf4c8996fb924"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A new session. The previous refresh token is now revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LoginResponse"
                }
              }
            }
          },
          "400": {
            "description": "The payload failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "VALIDATION_FAILED",
                  "message": "request validation failed",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "401": {
            "description": "The refresh token is invalid, expired, or already revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "TOKEN_REVOKED",
                  "message": "refresh token has been revoked or expired",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          },
          "403": {
            "description": "The account is blocked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "USER_BLOCKED",
                  "message": "user account is blocked",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "cURL",
            "source": "curl -sS -X POST \"https://api.sdx.zappy.com.br/iam/v1/auth/refresh\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"refresh_token\":\"e3b0c44298fc1c149afbf4c8996fb924\"}'\n"
          },
          {
            "lang": "Go",
            "label": "Go",
            "source": "package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := `{\n\t  \"refresh_token\": \"e3b0c44298fc1c149afbf4c8996fb924\"\n\t}`\n\n\treq, err := http.NewRequest(\"POST\", \"https://api.sdx.zappy.com.br/iam/v1/auth/refresh\", strings.NewReader(body))\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\n\tpayload, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.StatusCode, string(payload))\n}\n"
          },
          {
            "lang": "PHP",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init(\"https://api.sdx.zappy.com.br/iam/v1/auth/refresh\");\ncurl_setopt($ch, CURLOPT_CUSTOMREQUEST, \"POST\");\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, [\"Content-Type: application/json\"]);\n\n$payload = <<<'JSON'\n{\n  \"refresh_token\": \"e3b0c44298fc1c149afbf4c8996fb924\"\n}\nJSON;\n\ncurl_setopt($ch, CURLOPT_POSTFIELDS, $payload);\n\n$response = curl_exec($ch);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL, $response, PHP_EOL;\ncurl_close($ch);\n"
          },
          {
            "lang": "JavaScript",
            "label": "Node.js",
            "source": "const response = await fetch(\"https://api.sdx.zappy.com.br/iam/v1/auth/refresh\", {\n  method: \"POST\",\n  headers: {\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"refresh_token\": \"e3b0c44298fc1c149afbf4c8996fb924\"\n  }),\n});\n\nconsole.log(response.status, await response.json());\n"
          }
        ]
      }
    },
    "/iam/v1/auth/reset-password": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Set a new password",
        "description": "Consumes the single-use token from the reset e-mail and sets a new password.",
        "operationId": "resetPassword",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResetPasswordRequest"
              },
              "example": {
                "token": "9b2a5d6f3c11ceea467a9f1f8f14e45f",
                "new_password": "a-new-passphrase-2026"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The password is changed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessageResponse"
                },
                "example": {
                  "message": "password has been reset successfully"
                }
              }
            }
          },
          "400": {
            "description": "The token is invalid, expired, already consumed, or the payload failed validation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "INVALID_TOKEN",
                  "message": "invalid or expired reset token",
                  "trace_id": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Shell",
            "label": "cURL",
            "source": "curl -sS -X POST \"https://api.sdx.zappy.com.br/iam/v1/auth/reset-password\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"token\":\"9b2a5d6f3c11ceea467a9f1f8f14e45f\",\"new_password\":\"a-new-passphrase-2026\"}'\n"
          },
          {
            "lang": "Go",
            "label": "Go",
            "source": "package main\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"strings\"\n)\n\nfunc main() {\n\tbody := `{\n\t  \"token\": \"9b2a5d6f3c11ceea467a9f1f8f14e45f\",\n\t  \"new_password\": \"a-new-passphrase-2026\"\n\t}`\n\n\treq, err := http.NewRequest(\"POST\", \"https://api.sdx.zappy.com.br/iam/v1/auth/reset-password\", strings.NewReader(body))\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\treq.Header.Set(\"Content-Type\", \"application/json\")\n\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tdefer res.Body.Close()\n\n\tpayload, _ := io.ReadAll(res.Body)\n\tfmt.Println(res.StatusCode, string(payload))\n}\n"
          },
          {
            "lang": "PHP",
            "label": "PHP",
            "source": "<?php\n\n$ch = curl_init(\"https://api.sdx.zappy.com.br/iam/v1/auth/reset-password\");\ncurl_setopt($ch, CURLOPT_CUSTOMREQUEST, \"POST\");\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, [\"Content-Type: application/json\"]);\n\n$payload = <<<'JSON'\n{\n  \"token\": \"9b2a5d6f3c11ceea467a9f1f8f14e45f\",\n  \"new_password\": \"a-new-passphrase-2026\"\n}\nJSON;\n\ncurl_setopt($ch, CURLOPT_POSTFIELDS, $payload);\n\n$response = curl_exec($ch);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE), PHP_EOL, $response, PHP_EOL;\ncurl_close($ch);\n"
          },
          {
            "lang": "JavaScript",
            "label": "Node.js",
            "source": "const response = await fetch(\"https://api.sdx.zappy.com.br/iam/v1/auth/reset-password\", {\n  method: \"POST\",\n  headers: {\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    \"token\": \"9b2a5d6f3c11ceea467a9f1f8f14e45f\",\n    \"new_password\": \"a-new-passphrase-2026\"\n  }),\n});\n\nconsole.log(response.status, await response.json());\n"
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "TokenBasic": {
        "type": "http",
        "scheme": "basic",
        "description": "Machine credential issued by ZAPPY, sent as `Basic base64(client_id:client_secret)`.\n\nScoped to a single account or to a whole company. The secret is shown once at issuance and only its digest is stored."
      },
      "UserBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Short-lived access token from `POST /iam/v1/auth/login`, sent as `Bearer <token>`.\n\nIdentifies a person, not a system. Banking endpoints reject it."
      }
    },
    "schemas": {
      "AccountBalance": {
        "type": "object",
        "description": "Balance as embedded in a statement response. Note `total`, and an RFC 3339 nano timestamp.",
        "properties": {
          "total": {
            "type": "number",
            "format": "double",
            "multipleOf": 0.01,
            "description": "Amount in Brazilian reais with exactly two decimals. Never a string, never centavos.",
            "example": 1520.75
          },
          "blocked": {
            "type": "number",
            "format": "double",
            "multipleOf": 0.01,
            "description": "Amount in Brazilian reais with exactly two decimals. Never a string, never centavos.",
            "example": 0.0
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-09-22T13:40:11.482913Z"
          }
        }
      },
      "AccountBalanceResponse": {
        "type": "object",
        "description": "Standalone balance. Field names and the timestamp format differ from the balance embedded in a statement.",
        "properties": {
          "balance": {
            "type": "number",
            "format": "double",
            "multipleOf": 0.01,
            "description": "Amount in Brazilian reais with exactly two decimals. Never a string, never centavos.",
            "example": 1520.75
          },
          "blocked": {
            "type": "number",
            "format": "double",
            "multipleOf": 0.01,
            "description": "Held and not yet available for payout.",
            "example": 0.0
          },
          "updated_at": {
            "type": "string",
            "description": "RFC 3339 UTC timestamp, or an empty string when absent.",
            "example": "2026-09-22T13:40:11Z"
          }
        }
      },
      "AccountBankInfo": {
        "type": "object",
        "description": "The account's own coordinates in the Brazilian banking system.",
        "properties": {
          "bank_number": {
            "type": "string",
            "description": "COMPE bank code.",
            "example": "450"
          },
          "bank_branch": {
            "type": "string",
            "example": "0001"
          },
          "bank_account": {
            "type": "string",
            "example": "3048122"
          },
          "bank_account_digit": {
            "type": "string",
            "example": "7"
          }
        }
      },
      "AccountTransaction": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "5c7c1a0b-2f31-4d2e-9d9e-9a1b0f9c2c9e"
          },
          "type": {
            "type": "string",
            "enum": [
              "credit",
              "debit"
            ],
            "description": "Direction from this account's point of view.",
            "example": "credit"
          },
          "subtype": {
            "type": "string",
            "enum": [
              "pix"
            ],
            "example": "pix"
          },
          "operation": {
            "type": "string",
            "enum": [
              "Pix In",
              "Pix Out"
            ],
            "example": "Pix In"
          },
          "details": {
            "type": "string",
            "example": "PIX recebido"
          },
          "description": {
            "type": "string",
            "example": "Pedido 10492"
          },
          "document_number": {
            "type": "integer",
            "description": "Provider document identifier. **`0` when the provider's identifier is not numeric** — do not treat that as valid.",
            "example": 884213
          },
          "date": {
            "type": "string",
            "description": "RFC 3339 UTC timestamp, or an empty string when absent.",
            "example": "2026-09-22T13:40:11Z"
          },
          "value": {
            "type": "number",
            "format": "double",
            "multipleOf": 0.01,
            "description": "Amount in Brazilian reais with exactly two decimals. Never a string, never centavos.",
            "example": 250.0
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Provider identifier and end-to-end identifier, when the provider supplied them.",
            "example": [
              "884213",
              "E45000000202609221340abcdef123456"
            ]
          }
        }
      },
      "AccountTransactionsResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AccountTransaction"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/PaginationMeta"
          },
          "balance": {
            "$ref": "#/components/schemas/AccountBalance"
          },
          "account": {
            "$ref": "#/components/schemas/AccountBankInfo"
          }
        }
      },
      "Error": {
        "type": "object",
        "description": "The single error shape used by every endpoint.",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "Stable machine-readable code.",
            "example": "ZPY.VAL.006"
          },
          "message": {
            "type": "string",
            "description": "Human-readable explanation. Not for matching on.",
            "example": "account_id must be a UUID"
          },
          "trace_id": {
            "type": "string",
            "description": "Correlates this call with ZAPPY logs. Quote it in support requests.",
            "example": "0f9c2c9e-9a1b-4d2e-9d9e-5c7c1a0b2f31"
          }
        }
      },
      "ForgotPasswordRequest": {
        "type": "object",
        "required": [
          "email"
        ],
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "example": "ana.souza@empresa.com.br"
          }
        }
      },
      "GetWithdrawResponse": {
        "type": "object",
        "properties": {
          "reference": {
            "type": "string",
            "example": "payout-2026-09-22-0001"
          },
          "document_number": {
            "type": "integer",
            "example": 884219
          },
          "e2e_id": {
            "type": "string",
            "description": "Central Bank end-to-end identifier, once settled.",
            "example": "E45000000202609221341abcdef654321"
          },
          "origin": {
            "$ref": "#/components/schemas/Party"
          },
          "destination": {
            "$ref": "#/components/schemas/Party"
          },
          "payment_date": {
            "type": "string",
            "description": "RFC 3339 UTC timestamp, or an empty string when absent.",
            "example": "2026-09-22T13:40:11Z"
          },
          "status": {
            "type": "string",
            "description": "Provider settlement status.",
            "example": "paid"
          }
        }
      },
      "LoginRequest": {
        "type": "object",
        "required": [
          "username",
          "password"
        ],
        "properties": {
          "username": {
            "type": "string",
            "format": "email",
            "example": "ana.souza@empresa.com.br"
          },
          "password": {
            "type": "string",
            "format": "password",
            "minLength": 8,
            "maxLength": 64,
            "example": "correct-horse-battery"
          }
        }
      },
      "LoginResponse": {
        "type": "object",
        "description": "Two shapes share this schema. When a second factor is pending only `mfa_required` and `mfa_token` are present — a challenge must reveal nothing about the account. Otherwise the full session is returned.",
        "properties": {
          "access_token": {
            "type": "string",
            "example": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
          },
          "refresh_token": {
            "type": "string",
            "example": "e3b0c44298fc1c149afbf4c8996fb924"
          },
          "type": {
            "type": "string",
            "enum": [
              "Bearer"
            ],
            "example": "Bearer"
          },
          "expires_at": {
            "type": "integer",
            "format": "int64",
            "description": "Access-token expiry as Unix epoch **seconds**, not a timestamp string.",
            "example": 1790082011
          },
          "user": {
            "$ref": "#/components/schemas/LoginUser"
          },
          "mfa_required": {
            "type": "boolean",
            "description": "True when a second factor must be verified before a session is issued.",
            "example": true
          },
          "mfa_token": {
            "type": "string",
            "description": "Single-use challenge to present at `POST /iam/v1/auth/mfa`.",
            "example": "c7f1a0b2f3149afbf4c8996fb9241a1b"
          }
        }
      },
      "LoginUser": {
        "type": "object",
        "required": [
          "id",
          "name",
          "email",
          "roles"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "8f14e45f-ceea-467a-9f1f-9b2a5d6f3c11"
          },
          "name": {
            "type": "string",
            "example": "Ana Souza"
          },
          "email": {
            "type": "string",
            "format": "email",
            "example": "ana.souza@empresa.com.br"
          },
          "roles": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "company_admin"
            ]
          }
        }
      },
      "MFAVerifyRequest": {
        "type": "object",
        "required": [
          "mfa_token",
          "code"
        ],
        "properties": {
          "mfa_token": {
            "type": "string",
            "description": "The challenge returned by login.",
            "example": "c7f1a0b2f3149afbf4c8996fb9241a1b"
          },
          "code": {
            "type": "string",
            "minLength": 6,
            "maxLength": 32,
            "description": "Six-digit authenticator code, or a recovery code. The bounds span both.",
            "example": "418902"
          }
        }
      },
      "MessageResponse": {
        "type": "object",
        "required": [
          "message"
        ],
        "properties": {
          "message": {
            "type": "string",
            "example": "password has been reset successfully"
          }
        }
      },
      "PaginationMeta": {
        "type": "object",
        "required": [
          "page",
          "limit",
          "total"
        ],
        "properties": {
          "page": {
            "type": "integer",
            "example": 1
          },
          "limit": {
            "type": "integer",
            "example": 25
          },
          "total": {
            "type": "integer",
            "description": "Total matching records reported by the banking provider.",
            "example": 137
          }
        }
      },
      "Party": {
        "type": "object",
        "description": "One side of a settled transfer, as reported by the banking provider.",
        "properties": {
          "name": {
            "type": "string",
            "example": "Carlos Pereira"
          },
          "tax_number": {
            "type": "string",
            "description": "May be masked by the provider.",
            "example": "***.456.789-**"
          },
          "bank_account": {
            "type": "string",
            "example": "56789"
          },
          "bank_account_digit": {
            "type": "string",
            "example": "0"
          },
          "bank_branch": {
            "type": "string",
            "example": "1234"
          },
          "bank_number": {
            "type": "string",
            "example": "341"
          },
          "ispb": {
            "type": "string",
            "description": "Central Bank participant identifier.",
            "example": "60701190"
          },
          "spb": {
            "type": "string",
            "example": "341"
          }
        }
      },
      "PixKeyItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "2f315c7c-1a0b-4d2e-9d9e-9a1b0f9c2c9e"
          },
          "type": {
            "type": "string",
            "enum": [
              "cpf",
              "cnpj",
              "email",
              "phone",
              "evp"
            ],
            "example": "evp"
          },
          "key": {
            "type": "string",
            "example": "7b9f2c10-4a55-4b1e-9f21-0c3d8e6a1b42"
          },
          "status": {
            "type": "string",
            "example": "active"
          },
          "updated_at": {
            "type": "string",
            "description": "RFC 3339 UTC timestamp, or an empty string when absent.",
            "example": "2026-09-22T13:40:11Z"
          }
        }
      },
      "PixKeysResponse": {
        "type": "object",
        "description": "Not paginated. `meta` carries only a total.",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PixKeyItem"
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer",
                "example": 3
              }
            }
          }
        }
      },
      "PixQRCodeResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Empty on this endpoint.",
            "example": ""
          },
          "reference": {
            "type": "string",
            "example": "charge-10492"
          },
          "name": {
            "type": "string",
            "description": "Empty on this endpoint.",
            "example": ""
          },
          "description": {
            "type": "string",
            "example": ""
          },
          "type": {
            "type": "string",
            "enum": [
              "dynamic",
              "static"
            ],
            "example": "dynamic"
          },
          "key": {
            "type": "string",
            "example": "7b9f2c10-4a55-4b1e-9f21-0c3d8e6a1b42"
          },
          "payer": {
            "$ref": "#/components/schemas/QRCodePayer"
          },
          "receiver": {
            "$ref": "#/components/schemas/QRCodeReceiver"
          },
          "location": {
            "$ref": "#/components/schemas/QRCodeLocation"
          },
          "qrcode": {
            "$ref": "#/components/schemas/QRCodeInfo"
          },
          "reusable": {
            "type": "boolean",
            "example": false
          },
          "expires_at": {
            "type": "string",
            "description": "Honour this. An expired charge cannot be paid.",
            "example": "2026-09-22T13:40:11Z"
          },
          "value": {
            "type": "number",
            "format": "double",
            "multipleOf": 0.01,
            "description": "Amount in Brazilian reais with exactly two decimals. Never a string, never centavos.",
            "example": 250.0
          },
          "status": {
            "type": "string",
            "example": "pending"
          },
          "conciliation_id": {
            "type": "string",
            "description": "End-to-end identifier, once the charge settles.",
            "example": ""
          },
          "created_at": {
            "type": "string",
            "description": "RFC 3339 UTC timestamp, or an empty string when absent.",
            "example": "2026-09-22T13:40:11Z"
          }
        }
      },
      "PixTransaction": {
        "type": "object",
        "description": "Resolves a charge to its payment. While the charge is unpaid this returns the charge in a pending state rather than a 404.",
        "properties": {
          "reference": {
            "type": "string",
            "example": "charge-10492"
          },
          "document_number": {
            "type": "integer",
            "example": 884213
          },
          "e2e_id": {
            "type": "string",
            "example": "E45000000202609221340abcdef123456"
          },
          "origin": {
            "$ref": "#/components/schemas/Party"
          },
          "destination": {
            "$ref": "#/components/schemas/Party"
          },
          "payer": {
            "$ref": "#/components/schemas/PixTransactionPayer"
          },
          "qrcode": {
            "$ref": "#/components/schemas/PixTransactionQRCode"
          },
          "paid_at": {
            "type": "string",
            "description": "RFC 3339 UTC timestamp, or an empty string when absent.",
            "example": "2026-09-22T13:40:11Z"
          },
          "status": {
            "type": "string",
            "example": "paid"
          },
          "value": {
            "type": "number",
            "format": "double",
            "multipleOf": 0.01,
            "description": "Amount in Brazilian reais with exactly two decimals. Never a string, never centavos.",
            "example": 250.0
          }
        }
      },
      "PixTransactionPayer": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "Carlos Pereira"
          },
          "tax_number": {
            "type": "string",
            "example": "***.456.789-**"
          },
          "message": {
            "type": "string",
            "example": "Pedido 10492"
          }
        }
      },
      "PixTransactionQRCode": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "dynamic"
            ],
            "example": "dynamic"
          },
          "document_number": {
            "type": "integer",
            "example": 884213
          },
          "conciliation_id": {
            "type": "string",
            "example": "charge-10492"
          }
        }
      },
      "QRCodeInfo": {
        "type": "object",
        "properties": {
          "hash": {
            "type": "string",
            "description": "EMV copy-and-paste payload. Render as a QR image, or offer as text.",
            "example": "00020101021226830014br.gov.bcb.pix2561..."
          }
        }
      },
      "QRCodeLocation": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "example": "Sao Paulo"
          },
          "zip_code": {
            "type": "string",
            "example": "01310100"
          }
        }
      },
      "QRCodePayer": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "Carlos Pereira"
          },
          "tax_number": {
            "type": "string",
            "example": "123.456.789-09"
          },
          "message": {
            "type": "string",
            "example": "Pedido 10492"
          }
        }
      },
      "QRCodeReceiver": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "Empresa Exemplo LTDA"
          },
          "tax_number": {
            "type": "string",
            "example": "12.345.678/0001-95"
          }
        }
      },
      "RefreshRequest": {
        "type": "object",
        "required": [
          "refresh_token"
        ],
        "properties": {
          "refresh_token": {
            "type": "string",
            "description": "Single-use. Refreshing revokes it and issues a new pair.",
            "example": "e3b0c44298fc1c149afbf4c8996fb924"
          }
        }
      },
      "ResetPasswordRequest": {
        "type": "object",
        "required": [
          "token",
          "new_password"
        ],
        "properties": {
          "token": {
            "type": "string",
            "description": "Single-use token from the reset e-mail.",
            "example": "9b2a5d6f3c11ceea467a9f1f8f14e45f"
          },
          "new_password": {
            "type": "string",
            "format": "password",
            "minLength": 8,
            "maxLength": 64,
            "example": "a-new-passphrase-2026"
          }
        }
      },
      "WithdrawBankAccount": {
        "type": "object",
        "required": [
          "bank_number",
          "bank_branch",
          "bank_account"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "checking",
              "savings"
            ],
            "example": "checking"
          },
          "bank_number": {
            "type": "string",
            "example": "341"
          },
          "bank_branch": {
            "type": "string",
            "example": "1234"
          },
          "bank_account": {
            "type": "string",
            "example": "56789"
          },
          "bank_account_digit": {
            "type": "string",
            "example": "0"
          }
        }
      },
      "WithdrawDestination": {
        "type": "object",
        "required": [
          "name",
          "tax_number"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "Carlos Pereira"
          },
          "tax_number": {
            "type": "string",
            "description": "CPF (11 digits) or CNPJ (14 digits). Punctuation is stripped before validation.",
            "example": "123.456.789-09"
          }
        }
      },
      "WithdrawItem": {
        "allOf": [
          {
            "$ref": "#/components/schemas/GetWithdrawResponse"
          },
          {
            "type": "object",
            "properties": {
              "value": {
                "type": "number",
                "format": "double",
                "multipleOf": 0.01,
                "description": "Amount in Brazilian reais with exactly two decimals. Never a string, never centavos.",
                "example": 250.0
              }
            }
          }
        ]
      },
      "WithdrawPixKey": {
        "type": "object",
        "required": [
          "type",
          "key"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "cpf",
              "cnpj",
              "email",
              "phone",
              "evp"
            ],
            "example": "email"
          },
          "key": {
            "type": "string",
            "example": "carlos.pereira@exemplo.com.br"
          },
          "account_type": {
            "type": "string",
            "enum": [
              "checking",
              "savings"
            ],
            "example": "checking"
          }
        }
      },
      "WithdrawRequest": {
        "type": "object",
        "required": [
          "method",
          "reference",
          "destination",
          "date",
          "value"
        ],
        "description": "Exactly one of `pix` or `bank_account` must be present, matching `method`. The `qrcode` member exists in the wire format but the `qrcode` method is not supported.",
        "properties": {
          "method": {
            "type": "string",
            "enum": [
              "pix",
              "bank_account"
            ],
            "description": "`qrcode` is rejected with `ZPY.PIX.012`.",
            "example": "pix"
          },
          "reference": {
            "type": "string",
            "description": "**Your** identifier for this payout. Must be unique and stable — it is the lookup key afterwards and your protection against paying twice.",
            "example": "payout-2026-09-22-0001"
          },
          "destination": {
            "$ref": "#/components/schemas/WithdrawDestination"
          },
          "bank_account": {
            "$ref": "#/components/schemas/WithdrawBankAccount"
          },
          "pix": {
            "$ref": "#/components/schemas/WithdrawPixKey"
          },
          "description": {
            "type": "string",
            "maxLength": 1024,
            "example": "Repasse semanal"
          },
          "message": {
            "type": "string",
            "maxLength": 1024,
            "description": "Shown to the receiver where the provider supports it.",
            "example": "Obrigado!"
          },
          "date": {
            "type": "string",
            "format": "date",
            "example": "2026-09-22",
            "description": "Must be **today in UTC**. Scheduled payouts are rejected with `ZPY.VAL.008`."
          },
          "value": {
            "type": "number",
            "format": "double",
            "multipleOf": 0.01,
            "description": "Must be greater than zero.",
            "example": 250.0
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "repasse",
              "semanal"
            ]
          }
        }
      },
      "WithdrawResponse": {
        "type": "object",
        "properties": {
          "reference": {
            "type": "string",
            "example": "payout-2026-09-22-0001"
          },
          "method": {
            "type": "string",
            "enum": [
              "pix",
              "bank_account"
            ],
            "example": "pix"
          },
          "value": {
            "type": "number",
            "format": "double",
            "multipleOf": 0.01,
            "description": "Amount in Brazilian reais with exactly two decimals. Never a string, never centavos.",
            "example": 250.0
          },
          "document_number": {
            "type": "integer",
            "description": "`0` when the provider identifier is not numeric.",
            "example": 884219
          },
          "status": {
            "type": "string",
            "enum": [
              "processing"
            ],
            "description": "Always `processing` on acceptance. Settlement is asynchronous — poll the payout to see it advance.",
            "example": "processing"
          },
          "updated_at": {
            "type": "string",
            "description": "RFC 3339 UTC timestamp, or an empty string when absent.",
            "example": "2026-09-22T13:40:11Z"
          }
        }
      },
      "WithdrawsResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WithdrawItem"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/PaginationMeta"
          }
        }
      }
    }
  }
}