{ "openapi": "3.1.0", "info": { "title": "Clara API", "summary": "Corporate card and spend management API for Mexico, Brazil, and Colombia.", "description": "Use the Clara API to manage corporate cards, retrieve transactions, provision users, reconcile billing statements, download transaction documents, and automate spend-management workflows. Every API request requires both mutual TLS and an OAuth 2.0 Bearer token. This docs-published schema is derived from the current Clara developer documentation and should be checked against backend-owned API contracts before being treated as exhaustive.", "version": "3.0.0", "contact": { "name": "Clara Integration Support", "email": "integration.support.mx@clara.team", "url": "https://developers.clara.team" } }, "x-source": "Derived from the developers.clara.team documentation in this repository. Replace with the backend-owned OpenAPI contract if one is available.", "servers": [ { "url": "https://public-api.mx.clara.com", "description": "Mexico production" }, { "url": "https://public-api.br.clara.com", "description": "Brazil production" }, { "url": "https://public-api.co.clara.com", "description": "Colombia production" }, { "url": "https://public-api.mx.clara.com/api-test", "description": "Mexico sandbox. Use the same paths without the leading /api segment when testing, for example /v3/transactions." }, { "url": "https://public-api.br.clara.com/api-test", "description": "Brazil sandbox. Use the same paths without the leading /api segment when testing, for example /v3/transactions." }, { "url": "https://public-api.co.clara.com/api-test", "description": "Colombia sandbox. Use the same paths without the leading /api segment when testing, for example /v3/transactions." } ], "security": [ { "MutualTLS": [], "BearerAuth": [] } ], "tags": [ { "name": "Authentication", "description": "OAuth token exchange. Requests also require mutual TLS." }, { "name": "Cards", "description": "Create, list, retrieve, lock, unlock, update, and cancel corporate cards." }, { "name": "Transactions", "description": "Search card transactions and retrieve linked documents or fiscal data." }, { "name": "Users", "description": "Create, update, retrieve, delete, and filter users by identity, role, status, manager, or location." }, { "name": "Invoices", "description": "Retrieve Mexico CFDI invoice metadata linked to transactions." }, { "name": "Extracted Documents", "description": "Retrieve structured invoice, receipt, and other document data extracted from transactions." }, { "name": "Reimbursements", "description": "Retrieve reimbursement data for out-of-pocket expenses." }, { "name": "Billing Statements", "description": "Retrieve billing statements and statement transactions for reconciliation." }, { "name": "Digital Account", "description": "Brazil-only digital account movement search." }, { "name": "Accounts Payable", "description": "Create, cancel, and track Pix payments from the Clara digital account. Brazil only." } ], "paths": { "/oauth/token": { "post": { "operationId": "createOAuthToken", "summary": "Create an OAuth access token", "description": "Exchange client credentials for a short-lived Bearer token. Send the client ID and secret with HTTP Basic authentication and present the mTLS client certificate on the request.", "tags": [ "Authentication" ], "security": [ { "MutualTLS": [], "BasicAuth": [] } ], "responses": { "200": { "description": "Access token created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthTokenResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v3/cards": { "get": { "operationId": "listCardsV3", "summary": "List cards", "description": "List corporate cards with optional filters for cardholder, card status, periodicity, type, or ERP user ID.", "tags": [ "Cards" ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Size" }, { "name": "userUuid", "in": "query", "description": "Filter cards that belong to a specific user UUID. Do not combine with userErpId.", "schema": { "type": "string", "format": "uuid" } }, { "name": "username", "in": "query", "description": "Filter by the cardholder username or email.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by card status.", "schema": { "type": "string", "enum": [ "ACTIVE", "BLOCKED", "CANCELLED", "EXPIRED" ] } }, { "name": "periodicity", "in": "query", "description": "Filter by spending-limit reset frequency.", "schema": { "$ref": "#/components/schemas/Periodicity" } }, { "name": "type", "in": "query", "description": "Filter by card product and format type.", "schema": { "$ref": "#/components/schemas/CardListType" } }, { "name": "userErpId", "in": "query", "description": "Filter by the cardholder ERP identifier. Do not combine with userUuid.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated cards.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardPageV3" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "operationId": "createCardV3", "summary": "Create a card", "description": "Create one virtual or physical card for an active user. Use webhooks or listCardsV3 to confirm asynchronous downstream state changes where applicable.", "tags": [ "Cards" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCardRequestV3" } } } }, "responses": { "200": { "description": "Created card.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardV3" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/BusinessValidation" } } } }, "/api/v3/cards/{uuid}": { "get": { "operationId": "getCardV3", "summary": "Get a card", "description": "Retrieve a single card by UUID.", "tags": [ "Cards" ], "parameters": [ { "$ref": "#/components/parameters/CardUuid" } ], "responses": { "200": { "description": "Card details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardV3" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "operationId": "deleteCardV3", "summary": "Cancel a card", "description": "Cancel a card permanently. The card cannot be recovered after deletion.", "tags": [ "Cards" ], "parameters": [ { "$ref": "#/components/parameters/CardUuid" } ], "responses": { "204": { "description": "Card cancelled." }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v3/cards/{uuid}/lock": { "patch": { "operationId": "setCardLockV3", "summary": "Lock or unlock a card", "description": "Lock or unlock one card. Use lockCode 16 for standard API-initiated locks.", "tags": [ "Cards" ], "parameters": [ { "$ref": "#/components/parameters/CardUuid" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetCardLockRequestV3" } } } }, "responses": { "200": { "description": "Updated card.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardV3" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v3/cards/{uuid}/threshold": { "patch": { "operationId": "updateCardThresholdV3", "summary": "Update a card threshold", "description": "Update the spending limit for a card. The value is decimal currency units, not cents.", "tags": [ "Cards" ], "parameters": [ { "$ref": "#/components/parameters/CardUuid" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCardThresholdRequestV3" } } } }, "responses": { "200": { "description": "Updated card.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardV3" } } } }, "422": { "$ref": "#/components/responses/BusinessValidation" } } } }, "/api/v3/transactions": { "get": { "operationId": "listTransactionsV3", "summary": "List transactions", "description": "Search transactions by date range, card, user, status, type, or last update. Use this operation for reconciliation and spend analysis workflows.", "tags": [ "Transactions" ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Size" }, { "$ref": "#/components/parameters/OperationDateRangeStart" }, { "$ref": "#/components/parameters/OperationDateRangeEnd" }, { "$ref": "#/components/parameters/AccountingDateRangeStart" }, { "$ref": "#/components/parameters/AccountingDateRangeEnd" }, { "name": "userUuid", "in": "query", "description": "Filter by cardholder UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "cardUuid", "in": "query", "description": "Filter by card UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "cardLastDigits", "in": "query", "description": "Filter by the last four digits of the card number.", "schema": { "type": "string", "pattern": "^[0-9]{4}$" } }, { "name": "status", "in": "query", "description": "Filter by transaction status.", "schema": { "$ref": "#/components/schemas/TransactionStatus" } }, { "name": "operationTypeCode", "in": "query", "description": "Filter by Clara operation type code.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated transactions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionPageV3" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v3/transactions/{uuid}": { "get": { "operationId": "getTransactionV3", "summary": "Get a transaction", "description": "Retrieve a single transaction by UUID.", "tags": [ "Transactions" ], "parameters": [ { "$ref": "#/components/parameters/TransactionUuid" } ], "responses": { "200": { "description": "Transaction details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionV3" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v3/transactions/{uuid}/documents": { "get": { "operationId": "listTransactionDocumentsV3", "summary": "List transaction documents", "description": "Retrieve documents attached to a transaction, including pre-signed download URLs that expire after 12 hours.", "tags": [ "Transactions" ], "parameters": [ { "$ref": "#/components/parameters/TransactionUuid" } ], "responses": { "200": { "description": "Attached transaction documents.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionDocumentsResponseV3" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v3/users": { "get": { "operationId": "listUsersV3", "summary": "List users", "description": "List Clara users with filters for identity, role, status, tax identifier, ERP ID, location, manager, or creation date.", "tags": [ "Users" ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Size" }, { "name": "email", "in": "query", "description": "Filter by email address.", "schema": { "type": "string", "format": "email" } }, { "name": "fullName", "in": "query", "description": "Filter by full name.", "schema": { "type": "string" } }, { "name": "uuid", "in": "query", "description": "Filter by user UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "name", "in": "query", "description": "Filter by first name.", "schema": { "type": "string" } }, { "name": "lastName", "in": "query", "description": "Filter by last name.", "schema": { "type": "string" } }, { "name": "mobilePhone", "in": "query", "description": "Filter by mobile phone number.", "schema": { "type": "string" } }, { "name": "taxIdentifier", "in": "query", "description": "Filter by tax identifier.", "schema": { "type": "string" } }, { "name": "erpId", "in": "query", "description": "Filter by ERP identifier.", "schema": { "type": "string" } }, { "name": "createdAtStart", "in": "query", "description": "Filter users created on or after this date.", "schema": { "type": "string", "format": "date" } }, { "name": "createdAtEnd", "in": "query", "description": "Filter users created on or before this date.", "schema": { "type": "string", "format": "date" } }, { "name": "locationUuid", "in": "query", "description": "Filter by location UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "locationName", "in": "query", "description": "Filter by location name.", "schema": { "type": "string" } }, { "name": "managerUuid", "in": "query", "description": "Filter by manager UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Filter by user status.", "schema": { "$ref": "#/components/schemas/UserStatus" } }, { "name": "role", "in": "query", "description": "Filter by Clara user role.", "schema": { "$ref": "#/components/schemas/UserRole" } } ], "responses": { "200": { "description": "Paginated users.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserPageV3" } } } } } }, "post": { "operationId": "createUserV3", "summary": "Create a user", "description": "Create a user in the company account. Non-company-owner users generally require group and location assignment, and tax identifier length depends on country.", "tags": [ "Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserRequestV3" } } } }, "responses": { "201": { "description": "User created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserResponseV3" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/BusinessValidation" } } } }, "/api/v3/users/{uuid}": { "get": { "operationId": "getUserV3", "summary": "Get a user", "description": "Retrieve a single user by UUID.", "tags": [ "Users" ], "parameters": [ { "$ref": "#/components/parameters/UserUuid" } ], "responses": { "200": { "description": "User details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserV3" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "operationId": "updateUserV3", "summary": "Update a user", "description": "Update user profile, role, hierarchy, location, ERP, tax, or group membership fields. When cleanGroups is true, groupsToAdd must leave the user with at least one group.", "tags": [ "Users" ], "parameters": [ { "$ref": "#/components/parameters/UserUuid" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserRequestV3" } } } }, "responses": { "200": { "description": "User updated." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/BusinessValidation" } } }, "delete": { "operationId": "deleteUserV3", "summary": "Delete a user", "description": "Delete a user by UUID.", "tags": [ "Users" ], "parameters": [ { "$ref": "#/components/parameters/UserUuid" } ], "responses": { "204": { "description": "User deleted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v3/transactions/labels/bulk": { "post": { "operationId": "bulkBindTransactionLabelsV3", "summary": "Bulk bind labels to transactions", "description": "Bind one or more label UUIDs to multiple transactions in a single request.", "tags": [ "Transactions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkTransactionLabelsRequestV3" } } } }, "responses": { "200": { "description": "Labels bound to transactions." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v3/transactions/{uuid}/invoices": { "get": { "operationId": "listTransactionInvoicesV3", "summary": "List transaction invoices", "description": "Retrieve Mexico CFDI invoice metadata associated with a specific transaction. Invoice download URLs, when returned, are temporary.", "tags": [ "Invoices", "Transactions" ], "parameters": [ { "$ref": "#/components/parameters/TransactionUuid" } ], "responses": { "200": { "description": "Transaction invoice data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionInvoiceResponseV3" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v3/invoices": { "get": { "operationId": "listInvoicesV3", "summary": "List invoices", "description": "Find invoices with optional filters for invoice number, issuer RFC, transaction UUID, invoice ID, and document date range.", "tags": [ "Invoices" ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Size" }, { "name": "invoiceNumber", "in": "query", "description": "Filter by invoice number.", "schema": { "type": "string" } }, { "name": "issuerRfc", "in": "query", "description": "Filter by issuer RFC.", "schema": { "type": "string" } }, { "name": "transactionUuid", "in": "query", "description": "Filter by transaction UUID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "invoiceId", "in": "query", "description": "Filter by invoice ID.", "schema": { "type": "string" } }, { "name": "documentDateRangeStart", "in": "query", "description": "Invoice document-date range start. Use together with documentDateRangeEnd.", "schema": { "type": "string", "format": "date" } }, { "name": "documentDateRangeEnd", "in": "query", "description": "Invoice document-date range end. Use together with documentDateRangeStart.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Paginated invoices.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePageV3" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v3/transactions/{uuid}/extracted-documents": { "get": { "operationId": "listTransactionExtractedDocumentsV3", "summary": "List transaction extracted documents", "description": "Retrieve structured extracted documents associated with a transaction, with optional filters for document UUID, document type, and validation status.", "tags": [ "Extracted Documents", "Transactions" ], "parameters": [ { "$ref": "#/components/parameters/TransactionUuid" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Size" }, { "name": "documentUuid", "in": "query", "description": "Filter by extracted document UUID. Some docs also refer to this filter as uuid.", "schema": { "type": "string", "format": "uuid" } }, { "name": "type", "in": "query", "description": "Filter by extracted document type.", "schema": { "$ref": "#/components/schemas/ExtractedDocumentType" } }, { "name": "validationStatus", "in": "query", "description": "Filter by document validation status.", "schema": { "$ref": "#/components/schemas/DocumentValidationStatus" } } ], "responses": { "200": { "description": "Paginated extracted documents.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtractedDocumentPageV3" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v3/reimbursements": { "get": { "operationId": "listReimbursementsV3", "summary": "List reimbursements", "description": "Retrieve reimbursement records with filters for lifecycle status, requester, creation date, expense date, approval date, payment date, update date, category, and UUID.", "tags": [ "Reimbursements" ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Size" }, { "name": "requestCreationDateStart", "in": "query", "description": "Request creation date start in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "requestCreationDateEnd", "in": "query", "description": "Request creation date end in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "expenseDateStart", "in": "query", "description": "Expense date start in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "expenseDateEnd", "in": "query", "description": "Expense date end in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "finalApprovalDateStart", "in": "query", "description": "Final approval date start in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "finalApprovalDateEnd", "in": "query", "description": "Final approval date end in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "paymentDateStart", "in": "query", "description": "Payment date start in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "paymentDateEnd", "in": "query", "description": "Payment date end in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "lastUpdateDateStart", "in": "query", "description": "Last update date start in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "lastUpdateDateEnd", "in": "query", "description": "Last update date end in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "categoryCodes", "in": "query", "description": "Comma-separated category codes.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "name": "requesterUuids", "in": "query", "description": "Comma-separated requester UUIDs.", "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": false }, { "name": "statuses", "in": "query", "description": "Comma-separated reimbursement statuses.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ReimbursementStatus" } }, "style": "form", "explode": false }, { "name": "requesterName", "in": "query", "description": "Filter by requester name.", "schema": { "type": "string" } }, { "name": "uuids", "in": "query", "description": "Comma-separated reimbursement UUIDs.", "schema": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Paginated reimbursements.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReimbursementPageV3" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v3/reimbursements/{uuid}": { "get": { "operationId": "getReimbursementV3", "summary": "Get a reimbursement", "description": "Retrieve a single reimbursement by UUID.", "tags": [ "Reimbursements" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Reimbursement UUID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Reimbursement details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReimbursementV3" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v3/billing-statements": { "get": { "operationId": "listBillingStatementsV3", "summary": "List billing statements", "description": "List billing statements for reconciliation workflows.", "tags": [ "Billing Statements" ], "responses": { "200": { "description": "Billing statements.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BillingStatementV3" } } } } } } } }, "/api/v3/billing-statements/{uuid}/transactions": { "get": { "operationId": "listBillingStatementTransactionsV3", "summary": "List billing statement transactions", "description": "Retrieve transactions associated with one billing statement. Supports the same pagination and transaction filters as listTransactionsV3.", "tags": [ "Billing Statements", "Transactions" ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "Billing statement UUID.", "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Size" } ], "responses": { "200": { "description": "Paginated statement transactions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionPageV3" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v3/digital-accounts": { "get": { "operationId": "listDigitalAccountTransactionsV3", "summary": "List digital account transactions", "description": "Brazil-only endpoint for listing PIX, TED, bill, and transfer movements in the Clara digital account.", "tags": [ "Digital Account" ], "parameters": [ { "name": "startDate", "in": "query", "description": "Start date in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "endDate", "in": "query", "description": "End date in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, { "name": "transactionTypeName", "in": "query", "description": "Filter by digital account movement type.", "schema": { "type": "string", "enum": [ "PIX", "TED", "BILL", "TRANSACTION" ] } } ], "responses": { "200": { "description": "Digital account movements.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalAccountTransactionPageV3" } } } } } } }, "/api/v3/accounts-payable/pix": { "post": { "operationId": "createPixPaymentV3", "summary": "Create a Pix payment", "description": "Accept a Pix payment for asynchronous processing. The destination is inferred from the populated fields: paymentMethod.dictKey + dictKeyType for a Pix key, paymentMethod.qrCode for a QR, or a complete beneficiary with neither for bank details. A 202 means accepted, not paid: poll GET /api/v3/accounts-payable/{externalId} for the outcome. Requires the write:accounts-payable/pix grant. Brazil only.", "tags": [ "Accounts Payable" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePixPaymentRequestV3" }, "examples": { "pixKey": { "summary": "Pix key, immediate", "value": { "externalId": "a0c82a20-ac09-4cfd-b429-d0623585911e", "amount": 520.5, "description": "Invoice 2026-04 settlement", "paymentMethod": { "type": "PIX", "dictKey": "maria.silva@example.com", "dictKeyType": "EMAIL" }, "beneficiary": { "documentNumber": "12345678901" } } }, "qrCode": { "summary": "QR code, immediate (amount defined by the QR)", "value": { "externalId": "7c2e4a18-9d6b-4f35-a1c8-0e5b3d9f6a27", "description": "Supplier QR, amount defined by the QR", "paymentMethod": { "type": "PIX", "qrCode": "00020126580014br.gov.bcb.pix0136maria.silva@example.com5204000053039865802BR6009SAO PAULO62070503***6304ABCD" } } }, "bankDetails": { "summary": "Bank details, immediate", "value": { "externalId": "e91c07d4-2b58-4a6f-8d13-5c7e9a2b6f80", "amount": 3450.75, "description": "Contractor payment", "paymentMethod": { "type": "PIX" }, "beneficiary": { "name": "Maria Silva", "documentNumber": "12345678901", "bank": "60701190", "bankName": "Itau Unibanco S.A.", "accountType": "CACC", "accountNumber": "123456", "branch": "0001" } } }, "scheduled": { "summary": "Pix key, scheduled", "value": { "externalId": "3f1d9b6e-5c47-4a2b-8f0d-1b7a9c5e2d34", "amount": 1200, "description": "Rent, October", "paymentMethod": { "type": "PIX", "dictKey": "12345678901", "dictKeyType": "CPF", "desiredPaymentDate": "2026-10-01" } } } } } } }, "responses": { "202": { "description": "Payment accepted for processing. Not a settlement confirmation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixPaymentAcceptedV3" } } } }, "400": { "description": "INVALID_REQUEST: two destinations or none, a missing amount on a Pix-key or bank-details payment, an incomplete beneficiary, or a scheduled date before D+1.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "description": "Balance or Pix-limit pre-check rejected the payment: INSUFFICIENT_FUNDS or LIMIT_EXCEEDED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. Answered by the gateway with no body; X-RateLimit-Remaining, X-RateLimit-Replenish-Rate, X-RateLimit-Burst-Capacity, and X-RateLimit-Requested-Tokens carry the quota state. No Retry-After is returned." }, "503": { "description": "The payment service could not be reached or answered outside its contract. Retry later, then poll the payment by externalId before submitting it again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v3/accounts-payable/pix/{externalId}": { "delete": { "operationId": "cancelPixPaymentV3", "summary": "Cancel a scheduled Pix payment", "description": "Cancel a scheduled Pix payment that has not started executing. A cancellation can lose a race against execution, in which case it is rejected with NOT_CANCELLABLE. Requires the write:accounts-payable/pix grant. Brazil only.", "tags": [ "Accounts Payable" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "description": "Customer-supplied payment identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Cancellation accepted." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "NOT_FOUND: no payment with that externalId in the authenticated company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "NOT_CANCELLABLE (not scheduled, or execution already started) or ALREADY_CANCELLED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded. Answered by the gateway with no body; X-RateLimit-Remaining, X-RateLimit-Replenish-Rate, X-RateLimit-Burst-Capacity, and X-RateLimit-Requested-Tokens carry the quota state. No Retry-After is returned." }, "503": { "description": "The payment service could not be reached or answered outside its contract. Retry later, then poll the payment by externalId before submitting it again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v3/accounts-payable/{externalId}": { "get": { "operationId": "getAccountsPayablePaymentV3", "summary": "Get a Pix payment", "description": "Retrieve a Pix payment by its externalId. Poll this endpoint to observe the outcome of a created payment; PAID, FAILED, and CANCELLED are terminal and reached within 3 hours at worst. Requires the read:digital-account grant. Brazil only.", "tags": [ "Accounts Payable" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "description": "Customer-supplied payment identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixPaymentV3" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "description": "Rate limit exceeded. Answered by the gateway with no body; X-RateLimit-Remaining, X-RateLimit-Replenish-Rate, X-RateLimit-Burst-Capacity, and X-RateLimit-Requested-Tokens carry the quota state. No Retry-After is returned." } } } }, "/api/v3/accounts-payable": { "get": { "operationId": "listAccountsPayablePaymentsV3", "summary": "List Pix payments", "description": "List Pix payments with optional filters. Dates are YYYY-MM-DD in America/Sao_Paulo with inclusive bounds. Requires the read:digital-account grant. Brazil only.", "tags": [ "Accounts Payable" ], "parameters": [ { "name": "page", "in": "query", "description": "Zero-based page index.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "size", "in": "query", "description": "Page size.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "externalId", "in": "query", "description": "Exact match.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "Repeatable: pass it more than once to match several statuses.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "IN_PROCESS", "SCHEDULED", "PAID", "FAILED", "CANCELLED" ] } }, "style": "form", "explode": true }, { "name": "minAmount", "in": "query", "description": "Minimum amount.", "schema": { "type": "number", "format": "decimal" } }, { "name": "maxAmount", "in": "query", "description": "Maximum amount.", "schema": { "type": "number", "format": "decimal" } }, { "name": "createdFrom", "in": "query", "description": "Creation date range start.", "schema": { "type": "string", "format": "date" } }, { "name": "createdTo", "in": "query", "description": "Creation date range end.", "schema": { "type": "string", "format": "date" } }, { "name": "paidFrom", "in": "query", "description": "Settlement date range start. Matches PAID payments only.", "schema": { "type": "string", "format": "date" } }, { "name": "paidTo", "in": "query", "description": "Settlement date range end. Matches PAID payments only.", "schema": { "type": "string", "format": "date" } }, { "name": "beneficiaryName", "in": "query", "description": "Case-insensitive substring match.", "schema": { "type": "string" } }, { "name": "beneficiaryDocumentNumber", "in": "query", "description": "Case-insensitive substring match.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "One sort key as \",\". Fields: creationDate, amount, status. Direction: asc or desc. paymentDate is not sortable.", "schema": { "type": "string", "default": "creationDate,desc", "example": "creationDate,desc" } } ], "responses": { "200": { "description": "Paginated Pix payments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixPaymentPageV3" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "description": "Rate limit exceeded. Answered by the gateway with no body; X-RateLimit-Remaining, X-RateLimit-Replenish-Rate, X-RateLimit-Burst-Capacity, and X-RateLimit-Requested-Tokens carry the quota state. No Retry-After is returned." } } } }, "/api/v3/digital-accounts/balance": { "get": { "operationId": "getDigitalAccountBalanceV3", "summary": "Get digital account balance", "description": "Brazil-only endpoint returning the available balance of the authenticated company's checking and collateral accounts. The company is resolved from the token's taxId; the endpoint takes no parameters and requires the read:digital-account scope.", "tags": [ "Digital Account" ], "responses": { "200": { "description": "Digital account balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalAccountBalanceV3" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } } }, "components": { "securitySchemes": { "MutualTLS": { "type": "mutualTLS", "description": "All API requests require a valid Clara-issued X.509 client certificate." }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "OAuth 2.0 Bearer token from /oauth/token." }, "BasicAuth": { "type": "http", "scheme": "basic", "description": "Use CLIENT_ID:CLIENT_SECRET when requesting an access token." } }, "parameters": { "Page": { "name": "page", "in": "query", "description": "Zero-based page index.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, "Size": { "name": "size", "in": "query", "description": "Number of records per page. Use 100 for large exports unless an endpoint documents a lower limit.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, "CardUuid": { "name": "uuid", "in": "path", "required": true, "description": "Card UUID.", "schema": { "type": "string", "format": "uuid" } }, "TransactionUuid": { "name": "uuid", "in": "path", "required": true, "description": "Transaction UUID.", "schema": { "type": "string", "format": "uuid" } }, "UserUuid": { "name": "uuid", "in": "path", "required": true, "description": "User UUID.", "schema": { "type": "string", "format": "uuid" } }, "OperationDateRangeStart": { "name": "operationDateRangeStart", "in": "query", "description": "Inclusive operation-date start in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, "OperationDateRangeEnd": { "name": "operationDateRangeEnd", "in": "query", "description": "Inclusive operation-date end in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, "AccountingDateRangeStart": { "name": "accountingDateRangeStart", "in": "query", "description": "Inclusive accounting-date start in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } }, "AccountingDateRangeEnd": { "name": "accountingDateRangeEnd", "in": "query", "description": "Inclusive accounting-date end in YYYY-MM-DD format.", "schema": { "type": "string", "format": "date" } } }, "responses": { "BadRequest": { "description": "Bad request. Fix invalid parameters or missing fields before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Unauthorized. Refresh the token or verify mTLS certificate configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "Forbidden. The token is valid but lacks permission for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "BusinessValidation": { "description": "Business validation error. The request is well formed but violates a Clara business rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ServiceUnavailable": { "description": "Service unavailable. A downstream dependency did not respond; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "OAuthTokenResponse": { "type": "object", "required": [ "access_token", "token_type", "expires_in" ], "properties": { "access_token": { "type": "string", "description": "JWT Bearer token." }, "token_type": { "type": "string", "const": "Bearer" }, "expires_in": { "type": "integer", "description": "Token lifetime in seconds." } } }, "ErrorResponse": { "type": "object", "required": [ "message" ], "properties": { "code": { "type": "string", "description": "Machine-readable Clara or HTTP error code when available." }, "message": { "type": "string", "description": "Human-readable error message." }, "timestamp": { "type": "string", "format": "date-time" }, "details": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true }, "Money": { "type": "object", "properties": { "value": { "type": "number", "description": "Decimal currency units, not cents." }, "amount": { "type": "number", "description": "Decimal currency units, not cents. Some responses use amount instead of value." }, "currency": { "type": "string", "enum": [ "MXN", "BRL", "COP" ] } }, "additionalProperties": true }, "Periodicity": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY" ] }, "CardListType": { "type": "string", "enum": [ "MASTER_WORLD_ELITE", "MASTER_CORPORATE", "MASTER_VIRTUAL", "VISA_PHYSICAL", "VISA_VIRTUAL" ] }, "CreateCardType": { "type": "string", "enum": [ "VIRTUAL", "PHYSICAL" ] }, "BusinessType": { "type": "string", "enum": [ "BUSINESS", "WORLD_ELITE" ] }, "CardV3": { "type": "object", "required": [ "uuid", "alias", "status", "maskedPan", "type" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "alias": { "type": "string" }, "status": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/StatusObject" } ] }, "claraStatus": { "type": "string", "deprecated": true, "description": "Deprecated as of May 2025. Use status instead." }, "lockCode": { "type": [ "string", "integer", "null" ] }, "maskedPan": { "type": "string" }, "threshold": { "type": "number" }, "periodicity": { "oneOf": [ { "$ref": "#/components/schemas/Periodicity" }, { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/Periodicity" } }, "additionalProperties": true } ] }, "type": { "oneOf": [ { "$ref": "#/components/schemas/CardListType" }, { "type": "object", "additionalProperties": true } ] }, "user": { "$ref": "#/components/schemas/CardUser" } }, "additionalProperties": true }, "CardUser": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "fullName": { "type": "string" }, "username": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "additionalProperties": true }, "CardPageV3": { "type": "object", "required": [ "content", "totalElements", "totalPages", "size", "number" ], "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/CardV3" } }, "totalElements": { "type": "integer" }, "totalPages": { "type": "integer" }, "size": { "type": "integer" }, "number": { "type": "integer" } } }, "CreateCardRequestV3": { "type": "object", "required": [ "type", "alias", "userUuid" ], "properties": { "type": { "$ref": "#/components/schemas/CreateCardType" }, "alias": { "type": "string", "minLength": 1 }, "userUuid": { "type": "string", "format": "uuid" }, "threshold": { "type": "number", "description": "Decimal currency units, not cents." }, "periodicity": { "$ref": "#/components/schemas/Periodicity" }, "businessType": { "$ref": "#/components/schemas/BusinessType" } }, "additionalProperties": false }, "SetCardLockRequestV3": { "type": "object", "required": [ "lockCode" ], "properties": { "lockCode": { "type": "integer", "description": "Use 16 for a standard API-initiated lock." } }, "additionalProperties": false }, "UpdateCardThresholdRequestV3": { "type": "object", "required": [ "threshold" ], "properties": { "threshold": { "type": "number", "minimum": 0, "description": "Decimal currency units, not cents." } }, "additionalProperties": false }, "StatusObject": { "type": "object", "properties": { "code": { "type": "string" }, "description": { "type": "string" } }, "additionalProperties": true }, "TransactionStatus": { "type": "string", "enum": [ "NOTIFICATION", "PRE_AUTHORIZED", "AUTHORIZED", "REJECTED", "SYSTEM_TRANSACTION" ] }, "TransactionType": { "type": "string", "enum": [ "PURCHASE", "REFUND", "FEE", "CREDIT", "PAYMENT" ] }, "TransactionV3": { "type": "object", "required": [ "uuid", "type", "status", "amountValue" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "type": { "$ref": "#/components/schemas/TransactionType" }, "transactionLabel": { "type": "string" }, "status": { "oneOf": [ { "$ref": "#/components/schemas/TransactionStatus" }, { "$ref": "#/components/schemas/StatusObject" } ] }, "amountValue": { "$ref": "#/components/schemas/Money" }, "originalAmount": { "$ref": "#/components/schemas/Money" }, "merchant": { "type": "object", "properties": { "name": { "type": "string" }, "category": { "type": "string" }, "mcc": { "type": "string" } }, "additionalProperties": true }, "card": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "lastFourDigits": { "type": "string" }, "maskedPan": { "type": "string" } }, "additionalProperties": true }, "user": { "$ref": "#/components/schemas/CardUser" }, "labels": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "billingStatement": { "$ref": "#/components/schemas/BillingStatementV3" }, "hasInvoice": { "type": [ "boolean", "object" ] }, "hasAttachments": { "type": [ "boolean", "object" ] }, "hasExtractedDocuments": { "type": [ "boolean", "object" ] }, "accountingFields": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "accountingStatus": { "$ref": "#/components/schemas/AccountingStatus" } }, "additionalProperties": true }, "TransactionPageV3": { "type": "object", "required": [ "content", "totalElements", "totalPages", "size", "number" ], "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionV3" } }, "totalElements": { "type": "integer" }, "totalPages": { "type": "integer" }, "size": { "type": "integer" }, "number": { "type": "integer" } } }, "TransactionDocumentsResponseV3": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "fileName": { "type": "string" }, "format": { "type": "string" }, "download": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "urlExpiration": { "type": "string", "format": "date-time" } }, "additionalProperties": true } }, "additionalProperties": true } } }, "additionalProperties": true }, "UserRole": { "type": "string", "enum": [ "EMPLOYEE", "MANAGER", "COMPANY_OWNER", "BOOKKEEPER" ] }, "UserStatus": { "type": "string", "enum": [ "ONBOARDING_CANDIDATE", "WAITING", "DELETED", "ACTIVE", "LOCKED", "INACTIVE", "PENDING", "MASTER_LOCKED", "CLARA_BLOCKED" ] }, "UserV3": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "fullName": { "type": "string" }, "name": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string", "format": "email" }, "mobilePhone": { "type": "string" }, "taxIdentifier": { "type": "string" }, "role": { "$ref": "#/components/schemas/UserRole" }, "status": { "oneOf": [ { "$ref": "#/components/schemas/UserStatus" }, { "$ref": "#/components/schemas/StatusObject" } ] }, "erpId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedResource" } }, "cards": { "type": "array", "items": { "$ref": "#/components/schemas/CardV3" } }, "manager": { "$ref": "#/components/schemas/CardUser" }, "location": { "$ref": "#/components/schemas/LinkedResource" } }, "additionalProperties": true }, "UserPageV3": { "type": "object", "required": [ "content", "totalElements" ], "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/UserV3" } }, "totalElements": { "type": "integer" }, "totalPages": { "type": "integer" }, "size": { "type": "integer" }, "number": { "type": "integer" } } }, "CreateUserRequestV3": { "type": "object", "required": [ "email", "name", "lastName", "mobilePhone", "role" ], "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "lastName": { "type": "string" }, "groups": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "lada": { "type": "string" }, "mobilePhone": { "type": "string" }, "role": { "$ref": "#/components/schemas/UserRole" }, "managerUuid": { "type": "string", "format": "uuid" }, "locationUuid": { "type": "string", "format": "uuid" }, "erpId": { "type": "string" }, "taxIdentifier": { "type": "string", "description": "Tax identifier. Documented country lengths: MX 11 or 13, CO 7-10, BR 11." }, "foreign": { "type": "boolean", "default": false } }, "additionalProperties": false }, "CreateUserResponseV3": { "type": "object", "required": [ "uuid" ], "properties": { "uuid": { "type": "string", "format": "uuid" } }, "additionalProperties": true }, "UpdateUserRequestV3": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "lastName": { "type": "string" }, "lada": { "type": "string", "description": "Must be provided together with mobilePhone when changing phone fields." }, "mobilePhone": { "type": "string", "description": "Must be provided together with lada when changing phone fields." }, "role": { "$ref": "#/components/schemas/UserRole" }, "locationUuid": { "type": "string", "format": "uuid" }, "erpId": { "type": "string" }, "taxIdentifier": { "type": "string", "description": "Tax identifier. Documented country lengths: MX 11 or 13, CO 7-10, BR 11." }, "managerUuid": { "type": "string", "format": "uuid" }, "groupsToAdd": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "groupsToRemove": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "cleanGroups": { "type": "boolean", "default": false } }, "additionalProperties": false }, "BulkTransactionLabelsRequestV3": { "type": "object", "required": [ "transactions" ], "properties": { "transactions": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "uuid", "labelsUuid" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "labelsUuid": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "additionalProperties": false } } }, "additionalProperties": false }, "InvoiceV3": { "type": "object", "properties": { "invoiceId": { "type": "string" }, "invoiceNumber": { "type": [ "string", "null" ] }, "taxRegime": { "type": "string" }, "issuer": { "type": "object", "properties": { "rfc": { "type": "string" }, "businessName": { "type": "string" } }, "additionalProperties": true }, "taxReceipts": { "type": "object", "additionalProperties": true }, "tax": { "type": "object", "additionalProperties": true }, "amount": { "type": "object", "properties": { "total": { "type": "number" }, "subTotal": { "type": "number" }, "currency": { "type": "string" } }, "additionalProperties": true }, "documentDate": { "type": "string", "format": "date" }, "xmlStatus": { "type": "string" }, "xmlCode": { "type": "string" } }, "additionalProperties": true }, "TransactionInvoiceResponseV3": { "type": "object", "properties": { "transactionUuid": { "type": "string", "format": "uuid" }, "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceV3" } }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceV3" } }, "totalElements": { "type": "integer" }, "totalPages": { "type": "integer" }, "size": { "type": "integer" }, "number": { "type": "integer" } }, "additionalProperties": true }, "InvoicePageV3": { "type": "object", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceV3" } }, "totalElements": { "type": "integer" }, "totalPages": { "type": "integer" }, "size": { "type": "integer" }, "number": { "type": "integer" }, "first": { "type": "boolean" }, "last": { "type": "boolean" }, "numberOfElements": { "type": "integer" }, "empty": { "type": "boolean" } }, "additionalProperties": true }, "ExtractedDocumentType": { "type": "string", "enum": [ "MEXICAN_FISCAL_INVOICE", "INVOICE", "RECEIPT", "OTHER" ] }, "DocumentValidationStatus": { "type": "string", "enum": [ "VALIDATED_BY_CLARA", "VALIDATED_BY_USER", "NOT_VERIFIED" ] }, "ExtractedDocumentV3": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "type": { "$ref": "#/components/schemas/ExtractedDocumentType" }, "userUuid": { "type": "string", "format": "uuid" }, "data": { "type": "object", "additionalProperties": true }, "fileValidation": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/DocumentValidationStatus" }, "date": { "type": "string", "format": "date-time" }, "user": { "type": "string" }, "userUuid": { "type": "string", "format": "uuid" } }, "additionalProperties": true } }, "additionalProperties": true }, "ExtractedDocumentPageV3": { "type": "object", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/ExtractedDocumentV3" } }, "totalElements": { "type": "integer" }, "totalPages": { "type": "integer" }, "size": { "type": "integer" }, "number": { "type": "integer" } }, "additionalProperties": true }, "ReimbursementStatus": { "type": "string", "enum": [ "PENDING", "APPROVED", "SENT_TO_PAY", "PAYMENT_IN_PROGRESS", "PAID", "REJECTED", "FINANCE_REJECTED", "CANCELLED", "NOT_FOUND", "UNAUTHORIZED" ] }, "LinkedResource": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "links": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "_links": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "ReimbursementV3": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "description": { "type": "string" }, "audit": { "type": "object", "additionalProperties": true }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedResource" } }, "merchant": { "type": "object", "additionalProperties": true }, "requester": { "$ref": "#/components/schemas/CardUser" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedResource" } }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedResource" } }, "amountValue": { "$ref": "#/components/schemas/Money" }, "validationStatus": { "type": "object", "properties": { "status": { "$ref": "#/components/schemas/ReimbursementStatus" }, "comment": { "type": "string" } }, "additionalProperties": true }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "paymentDetail": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "ReimbursementPageV3": { "type": "object", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/ReimbursementV3" } }, "totalElements": { "type": "integer" }, "totalPages": { "type": "integer" }, "size": { "type": "integer" }, "number": { "type": "integer" } }, "additionalProperties": true }, "BillingStatementV3": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "statementStartDate": { "type": "string", "format": "date" }, "statementEndDate": { "type": "string", "format": "date" }, "currency": { "type": "string", "enum": [ "MXN", "BRL", "COP" ] }, "totalAmount": { "type": "number" }, "status": { "type": "string", "enum": [ "OPEN", "CLOSED" ] }, "generatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "DigitalAccountTransactionPageV3": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "transactionDate": { "type": "string", "format": "date-time" }, "amount": { "type": "number" }, "method": { "type": "string" }, "type": { "type": "string" }, "description": { "type": "string" } }, "additionalProperties": true } }, "meta": { "type": "object", "properties": { "totalPages": { "type": "integer" }, "totalItems": { "type": "integer" }, "itemsPerPage": { "type": "integer" }, "currentPage": { "type": "integer" } }, "additionalProperties": true } }, "additionalProperties": true }, "AccountingStatus": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "NEEDS_REVIEW", "READY_TO_EXPORT", "EXPORTED" ], "description": "Accounting Module review status for this transaction, independent from the root-level auth/approval status field. Present for authorized operations (operation types OP and EC, exposed as AUTHORIZED and SYSTEM_TRANSACTION respectively); null for any other operation type." } }, "additionalProperties": true }, "PixPaymentMethodV3": { "type": "object", "required": [ "type" ], "description": "Pix payment method. The destination is inferred from which fields are populated: dictKey for a Pix key, qrCode for a QR, neither for bank details.", "properties": { "type": { "type": "string", "enum": [ "PIX" ], "example": "PIX" }, "dictKey": { "type": "string", "description": "Beneficiary Pix (DICT) key. Mutually exclusive with qrCode.", "example": "maria.silva@example.com" }, "dictKeyType": { "type": "string", "enum": [ "CPF", "CNPJ", "EMAIL", "PHONE", "EVP" ], "description": "Type of the Pix key. Required whenever dictKey is sent: CPF and CNPJ keys are both digit strings and cannot be told apart from the value.", "example": "EMAIL" }, "qrCode": { "type": "string", "description": "EMV copy-and-paste string of a static or dynamic Pix QR. Mutually exclusive with dictKey. Its amount, expiry, and schedulability are resolved asynchronously and surface through polling.", "example": "00020126580014br.gov.bcb.pix0136maria.silva@example.com5204000053039865802BR6009SAO PAULO62070503***6304ABCD" }, "desiredPaymentDate": { "type": "string", "format": "date", "description": "Scheduled execution date (YYYY-MM-DD, America/Sao_Paulo). Minimum D+1; omit to pay immediately. A dynamic immediate (cob) QR cannot be scheduled.", "example": "2026-10-01" } } }, "PixBeneficiaryRequestV3": { "type": "object", "description": "Beneficiary. Optional owner assertion for a Pix-key or QR payment, where only documentNumber is evaluated; required in full for a bank-details payment, where it is the destination.", "properties": { "name": { "type": "string", "description": "Beneficiary name. Required for a bank-details payment.", "example": "Maria Silva" }, "documentNumber": { "type": "string", "description": "Beneficiary CPF or CNPJ, digits only. Optional owner assertion for a Pix-key or QR payment; required for a bank-details payment.", "example": "12345678901" }, "bank": { "type": "string", "description": "Beneficiary institution ISPB or bank code. Required for a bank-details payment.", "example": "60701190" }, "bankName": { "type": "string", "description": "Beneficiary institution name. Required for a bank-details payment.", "example": "Itau Unibanco S.A." }, "accountType": { "type": "string", "description": "ISO 20022 account type: CACC (checking/current), SVGS (savings), TRAN (payment account), SLRY (salary). Required for a bank-details payment.", "example": "CACC", "enum": [ "CACC", "SVGS", "TRAN", "SLRY" ] }, "accountNumber": { "type": "string", "description": "Beneficiary account number. Required for a bank-details payment.", "example": "123456" }, "branch": { "type": "string", "description": "Beneficiary branch number. Required for a bank-details payment.", "example": "0001" } } }, "PixBeneficiaryV3": { "type": "object", "description": "Beneficiary as resolved by payment execution. Null until the destination is resolved.", "properties": { "name": { "type": "string", "description": "Beneficiary name.", "example": "Maria Silva" }, "documentNumber": { "type": "string", "description": "Beneficiary CPF or CNPJ, digits only.", "example": "12345678901" }, "bank": { "type": "string", "description": "Beneficiary institution ISPB or bank code.", "example": "60701190" }, "bankName": { "type": "string", "description": "Beneficiary institution name.", "example": "Itau Unibanco S.A." }, "accountType": { "type": "string", "description": "ISO 20022 account type: CACC (checking/current), SVGS (savings), TRAN (payment account), SLRY (salary).", "example": "CACC", "enum": [ "CACC", "SVGS", "TRAN", "SLRY" ] }, "accountNumber": { "type": "string", "description": "Beneficiary account number.", "example": "123456" }, "branch": { "type": "string", "description": "Beneficiary branch number.", "example": "0001" } } }, "CreatePixPaymentRequestV3": { "type": "object", "required": [ "externalId", "paymentMethod" ], "properties": { "externalId": { "type": "string", "format": "uuid", "description": "Customer-generated payment identifier and company-scoped idempotency key. Re-sending the same value answers 202 without creating a second payment.", "example": "a0c82a20-ac09-4cfd-b429-d0623585911e" }, "amount": { "type": "number", "format": "decimal", "description": "Amount in BRL, greater than zero, at most 2 decimals. Required for Pix-key and bank-details payments; optional for a QR payment whose QR defines the amount.", "example": 520.5 }, "description": { "type": "string", "maxLength": 140, "description": "Free-text description of the payment.", "example": "Invoice 2026-04 settlement" }, "paymentMethod": { "$ref": "#/components/schemas/PixPaymentMethodV3" }, "beneficiary": { "$ref": "#/components/schemas/PixBeneficiaryRequestV3" } } }, "PixPaymentAcceptedV3": { "type": "object", "description": "Acknowledgement that the payment was accepted for processing. Not a settlement confirmation: poll the payment for its outcome.", "properties": { "externalId": { "type": "string", "format": "uuid", "example": "a0c82a20-ac09-4cfd-b429-d0623585911e" }, "status": { "type": "string", "enum": [ "IN_PROCESS" ], "example": "IN_PROCESS" }, "amount": { "type": [ "number", "null" ], "format": "decimal", "description": "Null while an amount-less QR is being resolved.", "example": 520.5 }, "paymentMethod": { "type": "string", "enum": [ "PIX" ], "example": "PIX" } } }, "PixPaymentErrorV3": { "type": "object", "description": "Failure detail of a FAILED payment. Integrate against code; message is informational, may be reworded without a version change, and is English-only at launch.", "properties": { "code": { "type": "string", "enum": [ "AMOUNT_REQUIRED", "AMOUNT_MISMATCH", "BENEFICIARY_MISMATCH", "QR_INVALID", "QR_EXPIRED", "QR_NOT_FOUND", "PIX_KEY_INVALID", "PIX_KEY_NOT_FOUND", "BENEFICIARY_ACCOUNT_ERROR", "PAYMENT_DATA_INVALID", "INSUFFICIENT_FUNDS", "LIMIT_EXCEEDED", "PAYMENT_NOT_ALLOWED", "PAYMENT_REJECTED", "SETTLEMENT_FAILED", "PROVIDER_UNAVAILABLE", "NOT_SCHEDULABLE", "SCHEDULE_DATE_INVALID", "SCHEDULE_FAILED", "PROCESSING_TIMEOUT", "PAYMENT_FAILED" ], "example": "INSUFFICIENT_FUNDS" }, "message": { "type": "string", "example": "The account balance is insufficient to complete the payment." } } }, "PixPaymentV3": { "type": "object", "properties": { "externalId": { "type": "string", "format": "uuid", "description": "Customer-supplied payment identifier, unique within the company.", "example": "a0c82a20-ac09-4cfd-b429-d0623585911e" }, "status": { "type": "string", "enum": [ "IN_PROCESS", "SCHEDULED", "PAID", "FAILED", "CANCELLED" ], "description": "PAID, FAILED, and CANCELLED are terminal. A payment reaches a terminal status within 3 hours at worst. A refunded payment remains PAID.", "example": "PAID" }, "amount": { "type": [ "number", "null" ], "format": "decimal", "description": "Null while an amount-less QR is being resolved.", "example": 520.5 }, "currencyCode": { "type": "string", "enum": [ "BRL" ], "example": "BRL" }, "paymentMethod": { "type": "string", "enum": [ "PIX" ], "example": "PIX" }, "description": { "type": "string", "example": "Invoice 2026-04 settlement" }, "beneficiary": { "$ref": "#/components/schemas/PixBeneficiaryV3" }, "pixEndToEndId": { "type": "string", "description": "Pix end-to-end identifier, available once the payment has settled.", "example": "E6070119020260901120000000000001" }, "error": { "$ref": "#/components/schemas/PixPaymentErrorV3" }, "creationDate": { "type": "string", "format": "date-time", "example": "2026-09-01T12:00:00Z" }, "paymentDate": { "type": "string", "format": "date", "description": "Settlement date. Filterable through paidFrom/paidTo but not sortable.", "example": "2026-09-01" } } }, "PixPaymentPageV3": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PixPaymentV3" } }, "page": { "type": "integer", "description": "Zero-based page index.", "example": 0 }, "size": { "type": "integer", "example": 20 }, "totalElements": { "type": "integer", "example": 1 }, "totalPages": { "type": "integer", "example": 1 } } }, "DigitalAccountBalanceV3": { "type": "object", "required": [ "checkingAccount" ], "properties": { "checkingAccount": { "type": "object", "required": [ "available" ], "properties": { "available": { "type": "number", "description": "Available balance of the checking account, in account-currency units (not cents)." } }, "additionalProperties": true }, "collateralAccount": { "type": "object", "required": [ "available" ], "properties": { "available": { "type": "number", "description": "Available balance of the collateral account; 0 when the company has none." } }, "additionalProperties": true } }, "additionalProperties": true } } }, "externalDocs": { "description": "Clara API documentation", "url": "https://developers.clara.team" } }