{ "openapi": "3.0.0", "info": { "version": "3.0.0", "title": "Banking & PIX API", "description": "Complete API documentation for the banking and PIX payment platform." }, "servers": [ { "url": "https://api.saq.digital/" } ], "security": [], "tags": [ { "name": "Authentication-API", "description": "Authentication-API endpoints" }, { "name": "Account-API", "description": "Account-API endpoints" }, { "name": "Cashin-API", "description": "Cashin-API endpoints" }, { "name": "Cashout-API", "description": "Cashout-API endpoints" }, { "name": "DICT-API", "description": "DICT-API endpoints" }, { "name": "Report-and-Query-API", "description": "Report-and-Query-API endpoints" }, { "name": "Webhook-API", "description": "Webhook-API endpoints" }, { "name": "Onboarding-API", "description": "Onboarding-API endpoints" } ], "paths": { "/v2/finance/auth-token/": { "post": { "operationId": "post_auth_token", "summary": "Auth Token", "description": "Generate OAuth 2.0 access token using client credentials. The access token is valid for 60 minutes.", "tags": [ "Authentication-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string", "description": "JWT access token to be used in the Authorization header" }, "token_type": { "type": "string", "description": "Always Bearer" }, "expires_in": { "type": "integer", "description": "Token lifetime in seconds (3600)" } } } } } }, "400": { "description": "Bad request - Invalid credentials" }, "401": { "description": "Unauthorized - Account disabled" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "type": "string", "description": "Public identifier for your application" }, "client_secret": { "type": "string", "description": "Confidential secret for authentication" } }, "required": [ "client_id", "client_secret" ] } } } } } }, "/v3/dict/key": { "post": { "operationId": "post_dict_key", "summary": "Include PIX Key", "description": "Registers a PIX key in the DICT (Brazilian PIX Key Directory) for the account identified by branch and number. Supports the following types: CPF, CNPJ, EMAIL, CELL_PHONE, and EVP (random key).", "tags": [ "DICT-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v3/dict/key/{key}": { "put": { "operationId": "put_dict_key_key", "summary": "Alter PIX Key", "description": "Changes the transactional account linked to a PIX key in the DICT (Brazilian PIX Key Directory). The origin and destination accounts must belong to the same client. EVP (random) keys cannot be altered. Requires HMAC signature for authentication.", "tags": [ "DICT-API" ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The active PIX key whose binding will be changed" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters or EVP key" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "404": { "description": "PIX key not found" }, "500": { "description": "Internal server error" } } }, "delete": { "operationId": "delete_dict_key_key", "summary": "Exclude PIX Key", "description": "Removes the active PIX key from the DICT (Brazilian PIX Key Directory) and marks the key as inactive in the local database. The key is identified by the value provided in the request path.", "tags": [ "DICT-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The key identifier" } ] } }, "/v3/dict/key/verifications/send": { "post": { "operationId": "post_dict_key_verifications_send", "summary": "Request PIX Key Verification (OTP)", "description": "Requests the sending of an OTP (One-Time Password) code via email or SMS to validate ownership of a PIX key of type EMAIL or CELL_PHONE before registering it in the DICT (Brazilian PIX Key Directory).", "tags": [ "DICT-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v3/webhooks/logs": { "get": { "operationId": "get_webhook_webhooks_logs", "summary": "List Webhook Logs", "description": "This API retrieves webhook execution logs for your account. It returns a paginated history of all webhook delivery attempts, including request details, responses, and status codes. Use this endpoint to monitor webhook deliveries and troubleshoot issues.", "tags": [ "Webhook-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } } } }, "/v3/webhooks/resend": { "get": { "operationId": "get_webhook_webhooks_resend", "summary": "List Webhook Resend Logs", "description": "Lists webhook resend request logs created by the authenticated user. Returns a paginated history of all resend requests, allowing filtering by status, reference object, and account mirror.", "tags": [ "Webhook-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } } }, "post": { "operationId": "post_webhook_webhooks_resend", "summary": "Resend Webhook", "description": "This API creates a webhook resend request for cash-in (QR Code) or cash-out (Transaction) events. You can resend specific webhooks by object ID or perform a bulk resend for all webhooks within a specified time period for an account.", "tags": [ "Webhook-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v2/list-my-pix-keys": { "get": { "operationId": "get_account_list-my-pix-keys", "summary": "List Account PIX Keys", "description": "This API retrieves all active PIX keys registered for a specific account. This endpoint is useful for displaying all PIX keys associated with an account in dashboards, payment forms, or account management interfaces.", "tags": [ "Account-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } } } }, "/v2/finance/get-balance": { "get": { "operationId": "get_account_balance", "summary": "Get Account Balance", "description": "This API retrieves the current balance information for a specific bank account. The response includes total balance, blocked amounts, scheduled amounts, and available balance for operations.", "tags": [ "Account-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "worked": { "type": "boolean", "example": true }, "amount": { "type": "number", "format": "float", "description": "Amount available for operations", "example": 14501.25 }, "amount_available": { "type": "number", "format": "float", "description": "Amount available for operations", "example": 14501.25 }, "amount_total": { "type": "number", "format": "float", "description": "Total balance in the account", "example": 15000.5 }, "amount_blocked": { "type": "number", "format": "float", "description": "Amount currently blocked/reserved", "example": 499.25 }, "amount_schedule": { "type": "number", "format": "float", "description": "Amount scheduled for future transactions", "example": 0 }, "last_update": { "type": "string", "format": "date-time", "description": "Timestamp of the last balance update", "example": "2026-06-02T10:30:00Z" }, "account_branch": { "type": "string", "description": "Branch/agency number", "example": "0001" }, "account_number": { "type": "string", "description": "Account number", "example": "12345678-9" } } } } } }, "400": { "description": "Bad request - Account not found or closed" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Account not found" }, "422": { "description": "Validation error - Missing required parameters" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "account_branch_identifier", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Branch/agency number of the account", "example": "0001" }, { "name": "account_number", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Account number to query balance", "example": "12345678-9" } ] } }, "/v3/account-statements/{account_branch_identifier}/{account_number}": { "get": { "operationId": "get_account_statement", "summary": "Get Account Statement", "description": "This API retrieves a paginated list of bank account transactions (statement) for a specific account within a date range. It uses cursor-based bidirectional pagination for efficient navigation through transaction history.", "tags": [ "Account-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "worked": { "type": "boolean", "example": true }, "next": { "type": "string", "nullable": true, "description": "URL for next page or null if last page", "example": "https://api.example.com/v3/account-statements/0001/12345678-9?start=2026-04-01T00:00:00Z&end=2026-04-30T23:59:59Z&limit=50&cursor=abc123&direction=next" }, "previous": { "type": "string", "nullable": true, "description": "URL for previous page or null if first page", "example": null }, "results": { "type": "array", "items": { "type": "object", "properties": { "credit_or_debit": { "type": "string", "enum": [ "CREDIT", "DEBIT" ], "example": "CREDIT" }, "transaction_type": { "type": "string", "example": "PIX_CASHIN" }, "amount": { "type": "number", "format": "float", "example": 500 }, "date_time": { "type": "string", "format": "date-time", "description": "Transaction date time in local timezone", "example": "2026-04-15T14:30:00-03:00" }, "date_time_utc": { "type": "string", "format": "date-time", "description": "Transaction date time in UTC", "example": "2026-04-15T17:30:00Z" }, "identification": { "type": "string", "nullable": true, "example": "E123456789202604151430ABCD1234" }, "code_transaction": { "type": "string", "nullable": true, "example": "E123456789202604151430ABCD1234" }, "code": { "type": "integer", "example": 98765 }, "qr_code_id": { "type": "integer", "nullable": true, "example": null }, "transaction_id": { "type": "integer", "nullable": true, "example": 5001 }, "tag_id": { "type": "string", "nullable": true, "example": "invoice-4321" }, "end_to_end": { "type": "string", "nullable": true, "example": "E123456789202604151430ABCD1234" }, "user_name": { "type": "string", "nullable": true, "example": "João Silva" }, "user_document": { "type": "string", "nullable": true, "example": "123.456.789-00" }, "user_agency": { "type": "string", "nullable": true, "example": "0002" }, "user_account": { "type": "string", "nullable": true, "example": "87654321-0" } } } } } } } } }, "400": { "description": "Bad request - Account not found, cursor expired, or invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "403": { "description": "Forbidden - Insufficient permissions" }, "404": { "description": "Not found - Account does not exist" }, "422": { "description": "Validation error - Invalid query parameters" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "account_branch_identifier", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Branch/agency number of the account", "example": "0001" }, { "name": "account_number", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Account number to retrieve statement", "example": "12345678-9" }, { "name": "start", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "description": "Start date and time for the transaction period (ISO 8601)", "example": "2026-04-01T00:00:00Z" }, { "name": "end", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" }, "description": "End date and time for the transaction period (ISO 8601)", "example": "2026-04-30T23:59:59Z" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Maximum number of transactions per page", "example": 50 }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor token for pagination (provided in next/previous URLs)", "example": "opaque_cursor_xyz123" }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "next", "previous" ] }, "description": "Pagination direction when using cursor (required if cursor is set)", "example": "next" } ] } }, "/v2/finance/chargebacks-pix-copy-and-paste/status": { "get": { "operationId": "get_chargeback_status", "summary": "Consult PIX QR Code Chargeback Status", "description": "This API allows you to consult the status of a previously created chargeback. The query can be made using either the chargeback ID or the End-to-End ID.", "tags": [ "Cashin-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } } } }, "/v2/finance/create-pix-copy-and-paste": { "post": { "operationId": "post_create_pix_copy_and_paste", "summary": "Generate a PIX Cash In (QR Code)", "description": "Generate a dynamic PIX QR Code (copy and paste) using a single endpoint. The type of QR Code is determined by the fields you send: provide only the essential fields (amount, source account, and expiration_date) with type_fine NONE to create a simplified immediate QR Code, or send the full set of fields (debtor information, due_date, expiration_date, and fine configuration) to create a charge QR Code similar to a boleto.", "tags": [ "Cashin-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v2/finance/chargebacks-pix-copy-and-paste": { "post": { "operationId": "post_create_chargeback", "summary": "Create PIX QR Code Chargeback", "description": "This API allows you to request a chargeback (full or partial) for a paid PIX QR Code. The chargeback processing is asynchronous and the status can be consulted later through the Chargeback Status API.", "tags": [ "Cashin-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v2/finance/decode-qrcode": { "post": { "operationId": "post_decode_qrcode", "summary": "Decode QR Code", "description": "This API decodes a PIX QR Code (copy and paste format) and returns detailed information about the payment, including receiver details, amount, and QR Code type. It supports static QR Codes, dynamic immediate payments, dynamic charges, and compound QR Codes.", "tags": [ "Cashin-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v2/finance/status-pix-copy-and-paste": { "get": { "operationId": "get_status_pix_copy_and_paste", "summary": "Check Status and Details of a Generated PIX Cash In by ID or EndToEnd", "description": "This API retrieves the status and comprehensive details of a previously generated PIX QR Code. Query by QR Code ID or EndToEndId. Returns payment status, amounts, debtor information, dates, and associated account details.", "tags": [ "Cashin-API" ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "QR Code ID. Either id or e2e_id must be provided, but not both." }, { "name": "e2e_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "EndToEndId of the QR Code. Either id or e2e_id must be provided, but not both." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters or QR Code not found" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } } } }, "/v2/finance/status-pix-copy-and-paste/tag": { "get": { "operationId": "get_status_pix_copy_and_paste_tag", "summary": "Check Status and Details of a Generated PIX Cash In by Tag", "description": "This API retrieves a list of all PIX QR Codes associated with a specific tag. Returns an array of QR Codes with their status, amounts, debtor information, dates, and account details. Useful for querying multiple QR Codes grouped by a common reference.", "tags": [ "Cashin-API" ], "parameters": [ { "name": "tag", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Tag used to group QR Codes (e.g., order number, invoice ID)" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } }, "400": { "description": "Bad request - No QR Codes found with this tag" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } } } }, "/v2/finance/receipt-transaction/file": { "get": { "operationId": "get_cashout_receipt-transaction_file", "summary": "Receipt Transaction File", "description": "This API generates and downloads a transaction receipt in PDF format. It supports both regular transactions and refunds, with multi-language support. The PDF includes all transaction details formatted for printing or digital sharing.", "tags": [ "Cashout-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } } } }, "/v2/finance/create-cashout": { "post": { "operationId": "post_cashout_create-cashout", "summary": "Create Cashout by PIX Key (Requires Approval)", "description": "Creates a new PIX cashout transaction using a PIX key. This endpoint initiates a transfer from the source account to a recipient identified by their PIX key. The transaction is created with `NEW` status and requires approval before being processed.", "tags": [ "Cashout-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v2/finance/create-cashout-self-approve": { "post": { "operationId": "post_cashout_create-cashout-self-approve", "summary": "Create Cashout Self-Approve (PIX Key)", "description": "Creates a new PIX cashout transaction using a PIX key and automatically approves it for processing. This endpoint combines the creation and approval steps, immediately transitioning the transaction from `NEW` to `PROCESSING` status. A background task is initiated to complete the transfer using the provided PIX key.", "tags": [ "Cashout-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v2/finance/create-cashout-manual": { "post": { "operationId": "post_cashout_create-cashout-manual", "summary": "Create Cashout Manual (Requires Approval)", "description": "Creates a new PIX cashout transaction using manual recipient account details. This endpoint allows you to initiate a transfer by specifying the complete recipient bank account information instead of using a PIX key. The transaction is created with `NEW` status and requires approval before being processed.", "tags": [ "Cashout-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v2/finance/create-cashoutmanual-self-approve": { "post": { "operationId": "post_cashout_create-cashoutmanual-self-approve", "summary": "Create Cashout Manual Self-Approve", "description": "Creates a new PIX cashout transaction using manual recipient account details and automatically approves it for processing. This endpoint combines the creation and approval steps, immediately transitioning the transaction from `NEW` to `PROCESSING` status. A background task is initiated to complete the transfer using the provided recipient account information.", "tags": [ "Cashout-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v2/finance/create-copy-and-paste-transfer": { "post": { "operationId": "post_cashout_create-copy-and-paste-transfer", "summary": "Create Copy and Paste Transfer (API)", "description": "This API processes a PIX payment using a QR Code in \"copia e cola\" (copy and paste) format via machine credentials (API audience). It decodes the QR Code, validates the payment details, creates and auto-approves the transaction. Authentication is done via Bearer token + HMAC signature.", "tags": [ "Cashout-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v2/finance/approve-cashout": { "post": { "operationId": "post_cashout_approve-cashout", "summary": "Approve Cashout", "description": "Approves a previously created cashout transaction, transitioning it from `NEW` status to `PROCESSING` status. This endpoint is used in the two-step approval workflow where a transaction is first created and then separately approved. Once approved, a background task is initiated to complete the transfer.", "tags": [ "Cashout-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v2/finance/approve-cashout-manual": { "post": { "operationId": "post_cashout_approve-cashout-manual", "summary": "Approve Cashout", "description": "Approves a previously created manual cashout transaction, transitioning it from `NEW` status to `PROCESSING` status. This endpoint is used in the two-step approval workflow where a manual cashout transaction is first created and then separately approved. Once approved, a background task is initiated to complete the transfer.", "tags": [ "Cashout-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v2/finance/create-manual-transfer": { "post": { "operationId": "post_cashout_create-manual-transfer", "summary": "Create Manual Transfer (PIX Key)", "description": "Creates a new PIX transfer with or without a PIX key. This endpoint supports transfers using a PIX key (CPF, CNPJ, phone, email, or random key) or manual transfers with full recipient account details. Requires MFA token validation and auto-approves the transaction.", "tags": [ "Cashout-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v3/dict/claim/{pix_key_claim_id}/confirm": { "post": { "operationId": "post_dict_claim_pix_key_claim_id_confirm", "summary": "Confirm PIX Key Claim", "description": "Confirm a PIX key claim as the donor (current key holder). This endpoint is used by the donor to explicitly confirm that they agree to transfer the key to the claimer.", "tags": [ "DICT-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "pix_key_claim_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The pix_key_claim_id identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v3/dict/claim/{pix_key_claim_id}/conclude": { "post": { "operationId": "post_dict_claim_pix_key_claim_id_conclude", "summary": "Conclude PIX Key Claim", "description": "Complete the final step of an ownership claim as the claimer. This endpoint is required **only for ownership claims** after the donor has confirmed the transfer. It is **not used for portability claims**, which complete automatically after donor confirmation.", "tags": [ "DICT-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "pix_key_claim_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The pix_key_claim_id identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v3/dict/claim/{pix_key_claim_id}/cancel": { "post": { "operationId": "post_dict_claim_pix_key_claim_id_cancel", "summary": "Cancel PIX Key Claim", "description": "Cancel an ongoing PIX key claim. Both the claimer (requesting party) and donor (current key holder) can cancel a claim while it is in OPEN or WAITING_RESOLUTION status.", "tags": [ "DICT-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "pix_key_claim_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The pix_key_claim_id identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v3/dict/claim": { "get": { "operationId": "get_dict_claim", "summary": "List PIX Key Claims", "description": "Retrieve a list of all PIX key claims associated with a specific account. This endpoint allows you to monitor the status of ongoing claims, view completed claims, and track claim history.", "tags": [ "DICT-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } } }, "post": { "operationId": "post_dict_claim", "summary": "Include PIX Key Claim", "description": "Initiate a new PIX key claim process to transfer a key via portability (same owner) or request ownership of a key registered to a different owner.", "tags": [ "DICT-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v3/meds/": { "get": { "operationId": "get_meds_list", "summary": "List MEDs", "description": "List all PIX MED (Mecanismo Especial de Devolução) infraction reports for your company using cursor-based pagination. Provides filtering capabilities by date range, status, reason, and infraction report status.", "tags": [ "MED-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } } } }, "/v3/meds/{med_id}": { "get": { "operationId": "get_med_details", "summary": "Get MED Details", "description": "Retrieves comprehensive details for a specific MED, including account information, bank details, QR code information, analysis data, and chargeback history.", "tags": [ "MED-API" ], "parameters": [ { "name": "med_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the MED infraction report" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "404": { "description": "MED not found" }, "500": { "description": "Internal server error" } } } }, "/v3/meds/{med_id}/file/upload": { "post": { "operationId": "post_med_upload_file", "summary": "Upload MED Response File", "description": "Upload a response file (evidence document) for a specific MED dispute. Supports PDF, DOC, DOCX, JPG, PNG and other document formats. The file is stored securely and associated with the MED for analysis purposes.", "tags": [ "MED-API" ], "parameters": [ { "name": "med_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the MED infraction report" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "File uploaded successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid file or MED status" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "404": { "description": "MED not found" }, "500": { "description": "Internal server error" } } } }, "/v3/meds/{med_id}/analysis": { "post": { "operationId": "post_med_analysis_result", "summary": "Submit MED Analysis Result", "description": "Submit your analysis decision for a MED dispute. You can accept the dispute (ACCEPTED) and specify the fraud type, or reject it (REJECTED). Accepted disputes trigger the refund process workflow.", "tags": [ "MED-API" ], "parameters": [ { "name": "med_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the MED infraction report" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Analysis submitted successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid MED status or missing fraud type" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "404": { "description": "MED not found" }, "500": { "description": "Internal server error" } } } }, "/v3/accounts/api/webhooks/{webhook_id}": { "patch": { "operationId": "patch_webhook_webhooks_webhook_id", "summary": "Update Webhook", "description": "This API allows you to update an existing webhook configuration. You can modify the URL, webhook type, or authentication tokens. The account association cannot be changed - to associate a webhook with a different account, you must delete and recreate it.", "tags": [ "Webhook-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The webhook_id identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } }, "delete": { "operationId": "delete_webhook_webhooks_webhook_id", "summary": "Delete Webhook", "description": "This API allows you to permanently delete a webhook. Once deleted, the webhook will no longer receive notifications, and the operation cannot be undone. Make sure you have the correct webhook ID before proceeding.", "tags": [ "Webhook-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } }, "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The webhook_id identifier" } ] } }, "/v3/accounts/api/webhooks": { "get": { "operationId": "get_webhook_webhooks", "summary": "List Webhooks", "description": "This API allows you to retrieve a list of registered webhooks for your account. You can filter by webhook ID, type, or specific account to narrow down the results.", "tags": [ "Webhook-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } } }, "post": { "operationId": "post_webhook_webhooks", "summary": "Create Webhook", "description": "This API allows you to register a new webhook to receive real-time notifications about transactions and events in your account. You can configure webhooks for different types of events and associate them with specific accounts.", "tags": [ "Webhook-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v2/finance/status-cashout/tag": { "get": { "operationId": "get_cashout_status-cashout_tag", "summary": "Status Cashout by Tag", "description": "Retrieves a list of all cashout transactions associated with a specific tag. This endpoint is useful for querying multiple transactions grouped by a common reference, such as batch payments, invoice numbers, or order IDs. Returns an array of transaction details.", "tags": [ "Cashout-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } } } }, "/v2/finance/status-cashout": { "get": { "operationId": "get_cashout_status-cashout", "summary": "Status Cashout", "description": "Retrieves the status and details of a cashout transaction. You can query by transaction ID, EndToEndId (e2e_id), or idempotency key. This endpoint provides comprehensive information about the transaction including status, amounts, recipient details, and timestamps.", "tags": [ "Cashout-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } } } }, "/v2/finance/cashin/{e2e}": { "get": { "operationId": "get_cashin_by_e2e", "summary": "Find a PIX Cash In by EndToEndId", "description": "Retrieves the full details of a received PIX cash in using its EndToEndId, including the amount, the fee charged, how much has already been refunded and the payer's identification.", "tags": [ "Cashin-API" ], "parameters": [ { "name": "e2e", "in": "path", "required": true, "schema": { "type": "string" }, "description": "EndToEndId of the received PIX cash in you want to retrieve" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "404": { "description": "Transaction not found" }, "500": { "description": "Internal server error" } } } }, "/v2/finance/chargeback": { "post": { "operationId": "post_cashin_chargeback", "summary": "Request a PIX Cash In Chargeback", "description": "Requests a full or partial refund of a PIX cash in you received. The refund is processed asynchronously and its progress can be followed through the chargeback status endpoint.", "tags": [ "Cashin-API" ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/v2/finance/chargeback/status": { "get": { "operationId": "get_cashin_chargeback_status", "summary": "Check PIX Cash In Chargeback Status", "description": "Checks the current status of a PIX cash in chargeback previously requested, using the identifier returned when the refund was created.", "tags": [ "Cashin-API" ], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Identifier of the chargeback request (UUID) returned when the refund was requested" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request - Invalid parameters" }, "401": { "description": "Unauthorized - Invalid or missing authentication" }, "500": { "description": "Internal server error" } } } }, "/v3/onboarding/form": { "post": { "operationId": "post_onboarding_create-form", "summary": "Create Own-Form Requisition", "description": "Starts an onboarding journey whose form is filled in your application. For PJ, send representative_document (CPF of the legal representative, who also performs the liveness when it is required). The response carries the access token required by every other own-form endpoint and, when the onboarding requires the proof of life, the liveness link the end user must complete. Without the proof of life, liveness_url and liveness_status come back null.", "tags": [ "Onboarding-API" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "document_legal_id", "email", "onboarding_type" ], "properties": { "document_legal_id": { "type": "string", "minLength": 11, "maxLength": 14, "description": "CPF for individual onboarding or CNPJ for company onboarding. The mask is removed and the check digits are validated.", "example": "11222333000181" }, "email": { "type": "string", "format": "email", "description": "Contact email for the onboarding journey.", "example": "contact@example.com" }, "onboarding_type": { "type": "string", "enum": [ "PF", "PJ" ], "description": "PF for an individual, PJ for a company.", "example": "PJ" }, "whitelabel_sigla": { "type": "string", "nullable": true, "maxLength": 50, "description": "Brand code of the white-label experience used for this journey. Must match an existing brand.", "example": "EXAMPLE" }, "representative_document": { "type": "string", "nullable": true, "description": "CPF of the legal representative, who also performs the liveness when it is required. Required for PJ. Do not send for PF. The mask is removed and the check digits are validated.", "example": "11144477735" } } } } } }, "responses": { "200": { "description": "An onboarding is already in progress for this document; the existing requisition is returned without a new access token", "content": { "application/json": { "schema": { "type": "object", "properties": { "worked": { "type": "boolean", "example": true }, "onboarding_requisition_id": { "type": "integer", "example": 42 }, "onboarding_link": { "type": "string", "nullable": true, "example": null }, "liveness_url": { "type": "string", "nullable": true, "example": "https://onboarding.example.com/liveness/abc123" }, "liveness_status": { "type": "string", "nullable": true, "enum": [ "PENDING", "PASSED", "FAILED" ], "example": "PENDING" }, "access_token": { "type": "string", "nullable": true, "example": null }, "status": { "type": "string", "enum": [ "PENDING", "APPROVED", "REPROVED", "IN_PROGRESS", "COMPLETED" ], "example": "IN_PROGRESS" } } } } } }, "201": { "description": "Onboarding requisition created", "content": { "application/json": { "schema": { "type": "object", "properties": { "worked": { "type": "boolean", "example": true }, "onboarding_requisition_id": { "type": "integer", "example": 42 }, "onboarding_link": { "type": "string", "nullable": true, "description": "Always null on the own-form journey.", "example": null }, "liveness_url": { "type": "string", "nullable": true, "description": "Link the end user must open to complete the liveness verification. null when the onboarding is configured without the proof of life.", "example": "https://onboarding.example.com/liveness/abc123" }, "liveness_status": { "type": "string", "nullable": true, "enum": [ "PENDING", "PASSED", "FAILED" ], "example": "PENDING" }, "access_token": { "type": "string", "nullable": true, "description": "Returned only when the requisition is created. Store it: every other own-form endpoint requires it in the X-Onboarding-Token header.", "example": "0Vv2mQ7bK8pQ3xZr5tY9wL1nC4dF6hJ8kM0pR2sT4uV" }, "status": { "type": "string", "enum": [ "PENDING", "APPROVED", "REPROVED", "IN_PROGRESS", "COMPLETED" ], "example": "PENDING" } } } } } }, "400": { "description": "The document cannot start a new onboarding requisition" }, "422": { "description": "Validation error - a field is missing or has an invalid value" } } } }, "/v3/onboarding/registration-update": { "post": { "operationId": "post_onboarding_registration-update", "summary": "Submit Registration Update", "description": "Starts a cadastral update for the authenticated account when the registration deadline has already expired. The document and the PF/PJ type come from the account; the body carries only the contact e-mail.", "tags": [ "Onboarding-API" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bearer access token of the account holder.", "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "Contact e-mail used for the cadastral update.", "example": "financeiro@example.com" } } } } } }, "responses": { "200": { "description": "Cadastral update started, or the existing in-progress update was returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "worked": { "type": "boolean", "example": true }, "onboarding_requisition_id": { "type": "integer", "example": 20401 }, "onboarding_link": { "type": "string", "nullable": true, "description": "Hosted update link the end user must open.", "example": "https://onboarding.example.com/journey/update123" }, "liveness_url": { "type": "string", "nullable": true, "example": null }, "liveness_status": { "type": "string", "nullable": true, "example": null }, "access_token": { "type": "string", "nullable": true, "example": null }, "status": { "type": "string", "enum": [ "PENDING", "APPROVED", "REPROVED", "IN_PROGRESS", "COMPLETED" ], "example": "PENDING" } } } } } }, "400": { "description": "The account cannot start a cadastral update" }, "401": { "description": "Missing or invalid Bearer token" }, "404": { "description": "Company not found" }, "422": { "description": "Validation error - email is missing or invalid" } } } }, "/v3/onboarding/registration-update/status": { "get": { "operationId": "get_onboarding_registration-update-status", "summary": "Get Registration Update Status", "description": "Returns whether the authenticated account must update its registration, if an update is already in progress, and whether POST /v3/onboarding/registration-update can be called.", "tags": [ "Onboarding-API" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Bearer access token of the account holder.", "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example" } ], "responses": { "200": { "description": "Current cadastral-update state of the authenticated account", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "NOT_REQUIRED", "ACTION_REQUIRED", "IN_PROGRESS", "IN_REVIEW" ], "example": "ACTION_REQUIRED" }, "deadline": { "type": "string", "format": "date", "nullable": true, "example": "2026-08-01" }, "days_remaining": { "type": "integer", "nullable": true, "example": -15 }, "blocked": { "type": "boolean", "example": true }, "can_start": { "type": "boolean", "example": true }, "onboarding_link": { "type": "string", "nullable": true, "example": null }, "rejection_reason": { "type": "string", "nullable": true, "example": null } } } } } }, "401": { "description": "Missing or invalid Bearer token" } } } }, "/v3/onboarding/{onboarding_requisition_id}": { "get": { "operationId": "get_onboarding_requisition-status", "summary": "Get Onboarding Requisition Status", "description": "Returns the current state of an onboarding journey: the provider status, the internal review status, the liveness verification state and the step your application should present next.", "tags": [ "Onboarding-API" ], "parameters": [ { "name": "onboarding_requisition_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identifier of the onboarding requisition.", "example": 42 }, { "name": "X-Onboarding-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Access token returned when the onboarding requisition was created.", "example": "0Vv2mQ7bK8pQ3xZr5tY9wL1nC4dF6hJ8kM0pR2sT4uV" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "worked": { "type": "boolean", "example": true }, "onboarding_requisition_id": { "type": "integer", "example": 42 }, "onboarding_type": { "type": "string", "nullable": true, "enum": [ "PF", "PJ" ], "example": "PJ" }, "status": { "type": "string", "enum": [ "PENDING", "APPROVED", "REPROVED", "IN_PROGRESS", "COMPLETED" ], "example": "IN_PROGRESS" }, "status_internal": { "type": "string", "nullable": true, "enum": [ "PENDING", "WAITING_APPROVAL", "APPROVED", "REJECTED" ], "example": null }, "liveness_status": { "type": "string", "nullable": true, "enum": [ "PENDING", "PASSED", "FAILED" ], "example": "PASSED" }, "current_step": { "type": "string", "nullable": true, "enum": [ "LIVENESS", "FORM", "PROCESSING", "REVIEW", "DONE" ], "example": "FORM" }, "liveness_url": { "type": "string", "nullable": true, "description": "Present only while the liveness verification is pending.", "example": null }, "liveness_attempts_left": { "type": "integer", "nullable": true, "example": 2 }, "submitted_at": { "type": "string", "format": "date-time", "nullable": true, "example": null }, "company": { "type": "object", "nullable": true, "description": "Official registry data of the company. Returned for company onboarding only, and null until the lookup completes.", "properties": { "official_name": { "type": "string", "nullable": true, "example": "EXAMPLE COMMERCE LTDA" }, "fantasy_name": { "type": "string", "nullable": true, "example": "Example Commerce" }, "opening_date": { "type": "string", "format": "date", "nullable": true, "example": "2018-03-12" }, "legal_nature": { "type": "string", "nullable": true, "example": "Sociedade Empresaria Limitada" }, "legal_nature_code": { "type": "string", "nullable": true, "example": "2062" }, "main_activity": { "type": "string", "nullable": true, "example": "Comercio varejista de artigos do vestuario" }, "main_activity_code": { "type": "string", "nullable": true, "example": "4781400" }, "joint_stock": { "type": "string", "nullable": true, "example": "100000.00" }, "zip_code": { "type": "string", "nullable": true, "example": "01310930" }, "state": { "type": "string", "nullable": true, "example": "SP" }, "city": { "type": "string", "nullable": true, "example": "Sao Paulo" }, "street": { "type": "string", "nullable": true, "example": "Avenida Paulista" }, "neighborhood": { "type": "string", "nullable": true, "example": "Bela Vista" }, "number": { "type": "string", "nullable": true, "example": "1578" }, "complement": { "type": "string", "nullable": true, "example": "Andar 12" } } }, "representative_document": { "type": "string", "nullable": true, "description": "CPF of the legal representative sent when the requisition was created. Returned for PJ onboarding only.", "example": "11144477735" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-09-15T18:24:11Z" } } } } } }, "404": { "description": "Onboarding requisition not found, or the access token is missing or incorrect" } } } }, "/v3/onboarding/{onboarding_requisition_id}/submit": { "post": { "operationId": "post_onboarding_submit-form", "summary": "Submit Onboarding Form", "description": "Submits the registration data collected by your own form, together with the identity documents encoded in base64. The request is accepted and the background analysis runs asynchronously. Every partner needs an IMAGE_FRONT document, and also a SELFIE when the onboarding is configured without the proof of life — that photo is what feeds the face comparison in the background analysis.", "tags": [ "Onboarding-API" ], "parameters": [ { "name": "onboarding_requisition_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identifier of the onboarding requisition.", "example": 42 }, { "name": "X-Onboarding-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Access token returned when the onboarding requisition was created.", "example": "0Vv2mQ7bK8pQ3xZr5tY9wL1nC4dF6hJ8kM0pR2sT4uV" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "partners", "documents", "accepted_terms" ], "properties": { "company": { "type": "object", "nullable": true, "description": "Required for company onboarding, not allowed for individual onboarding.", "properties": { "official_name": { "type": "string", "nullable": true, "maxLength": 255, "example": "EXAMPLE COMMERCE LTDA" }, "fantasy_name": { "type": "string", "nullable": true, "maxLength": 255, "example": "Example Commerce" }, "company_email": { "type": "string", "format": "email", "nullable": true, "example": "contact@example.com" }, "phone_number": { "type": "string", "nullable": true, "maxLength": 20, "example": "1133224455" }, "opening_date": { "type": "string", "format": "date", "nullable": true, "example": "2018-03-12" }, "zip_code": { "type": "string", "nullable": true, "maxLength": 10, "example": "01310930" }, "state": { "type": "string", "nullable": true, "maxLength": 2, "example": "SP" }, "city": { "type": "string", "nullable": true, "maxLength": 100, "example": "Sao Paulo" }, "street": { "type": "string", "nullable": true, "maxLength": 255, "example": "Avenida Paulista" }, "neighborhood": { "type": "string", "nullable": true, "maxLength": 100, "example": "Bela Vista" }, "number": { "type": "string", "nullable": true, "maxLength": 20, "example": "1578" }, "complement": { "type": "string", "nullable": true, "maxLength": 100, "example": "Andar 12" } } }, "partners": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "name", "cpf", "ownership_pct" ], "properties": { "name": { "type": "string", "maxLength": 255, "example": "Maria Oliveira Souza" }, "cpf": { "type": "string", "maxLength": 14, "description": "Partner CPF. The mask is removed and the check digits are validated.", "example": "12345678909" }, "birth_date": { "type": "string", "format": "date", "nullable": true, "example": "1985-07-22" }, "mother_name": { "type": "string", "nullable": true, "maxLength": 100, "example": "Ana Oliveira Souza" }, "father_name": { "type": "string", "nullable": true, "maxLength": 100, "example": "Jose Carlos Souza" }, "rg": { "type": "string", "nullable": true, "maxLength": 20, "example": "123456789" }, "rg_issuing_authority": { "type": "string", "nullable": true, "maxLength": 10, "example": "SSP" }, "rg_issue_state": { "type": "string", "nullable": true, "maxLength": 2, "example": "SP" }, "rg_issue_date": { "type": "string", "format": "date", "nullable": true, "example": "2010-05-03" }, "birth_place": { "type": "string", "nullable": true, "maxLength": 255, "example": "Sao Paulo" }, "birth_state": { "type": "string", "nullable": true, "maxLength": 2, "example": "SP" }, "nationality": { "type": "string", "nullable": true, "maxLength": 50, "example": "Brasileira" }, "email": { "type": "string", "format": "email", "nullable": true, "example": "maria.souza@example.com" }, "phone_number": { "type": "string", "nullable": true, "maxLength": 20, "example": "11987654321" }, "ownership_pct": { "type": "number", "minimum": 0, "maximum": 100, "description": "Ownership percentage. For company onboarding all partners must sum to exactly 100.", "example": 100 }, "is_legal_representative": { "type": "boolean", "default": false, "description": "Exactly one partner must be the legal representative in company onboarding. That partner's CPF must match representative_document from creation.", "example": true } } } }, "documents": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "type", "filename", "mime_type", "content" ], "properties": { "type": { "type": "string", "enum": [ "IMAGE_FRONT", "IMAGE_BACK", "SELFIE", "COMPANY_SOCIAL_CONTRACT", "OTHER", "RG_FRONT", "RG_BACK", "CNH_FRONT", "CNH_BACK", "CNH", "RNE_FRONT", "RNE_BACK", "PASSPORT" ], "description": "Canonical types IMAGE_FRONT, IMAGE_BACK, SELFIE, COMPANY_SOCIAL_CONTRACT and OTHER. Front/back aliases (RG_FRONT, RG_BACK, CNH_FRONT, CNH_BACK, CNH, RNE_FRONT, RNE_BACK, PASSPORT) are accepted case-insensitively and stored as IMAGE_FRONT or IMAGE_BACK.", "example": "RG_FRONT" }, "partner_cpf": { "type": "string", "nullable": true, "maxLength": 14, "description": "Required for IMAGE_FRONT, IMAGE_BACK and SELFIE. Must match a partner sent in the same request.", "example": "12345678909" }, "filename": { "type": "string", "maxLength": 255, "example": "id-front.jpg" }, "mime_type": { "type": "string", "maxLength": 100, "example": "image/jpeg" }, "content": { "type": "string", "format": "byte", "description": "Raw base64 content, without the data: prefix. Maximum 8 MB per file and 25 MB in total, measured after decoding.", "example": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB" } } } }, "accepted_terms": { "type": "boolean", "description": "Must be true.", "example": true } } } } } }, "responses": { "202": { "description": "Form accepted for analysis", "content": { "application/json": { "schema": { "type": "object", "properties": { "worked": { "type": "boolean", "example": true }, "onboarding_requisition_id": { "type": "integer", "example": 42 }, "submitted_at": { "type": "string", "format": "date-time", "example": "2026-09-15T18:24:11Z" } } } } } }, "400": { "description": "The form data or the attached documents did not pass validation" }, "404": { "description": "Onboarding requisition not found, or the access token is missing or incorrect" }, "409": { "description": "The form was already submitted for this requisition" }, "412": { "description": "The onboarding requires the proof of life and the liveness verification has not passed yet, or the requisition belongs to the provider-hosted journey and has no platform form" }, "413": { "description": "A document exceeds 8 MB, or the documents exceed 25 MB in total" }, "422": { "description": "Validation error - a field is missing or has an invalid value" } } } }, "/v3/onboarding/{onboarding_requisition_id}/liveness/retry": { "post": { "operationId": "post_onboarding_liveness-retry", "summary": "Retry Liveness Verification", "description": "Opens a new liveness verification attempt after a failed one and returns the fresh link for the end user, together with how many attempts are still available.", "tags": [ "Onboarding-API" ], "parameters": [ { "name": "onboarding_requisition_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identifier of the onboarding requisition.", "example": 42 }, { "name": "X-Onboarding-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Access token returned when the onboarding requisition was created.", "example": "0Vv2mQ7bK8pQ3xZr5tY9wL1nC4dF6hJ8kM0pR2sT4uV" } ], "responses": { "200": { "description": "A new liveness attempt was opened", "content": { "application/json": { "schema": { "type": "object", "properties": { "worked": { "type": "boolean", "example": true }, "liveness_url": { "type": "string", "nullable": true, "example": "https://onboarding.example.com/liveness/def456" }, "liveness_attempts_left": { "type": "integer", "description": "Attempts still available after this one.", "example": 1 } } } } } }, "400": { "description": "The liveness is not in a state that allows another attempt, or no attempts are left" }, "404": { "description": "Onboarding requisition not found, or the access token is missing or incorrect" } } } }, "/v3/onboarding/{onboarding_requisition_id}/liveness/refresh": { "post": { "operationId": "post_onboarding_liveness-refresh", "summary": "Refresh Liveness Result", "description": "Re-checks the liveness verdict and picks it up when it is already available. Use it when the end user finished the verification but the status endpoint still reports it as pending.", "tags": [ "Onboarding-API" ], "parameters": [ { "name": "onboarding_requisition_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identifier of the onboarding requisition.", "example": 42 }, { "name": "X-Onboarding-Token", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Access token returned when the onboarding requisition was created.", "example": "0Vv2mQ7bK8pQ3xZr5tY9wL1nC4dF6hJ8kM0pR2sT4uV" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "worked": { "type": "boolean", "example": true }, "enqueued": { "type": "boolean", "description": "True when a final verdict was found and is being applied; false when there is nothing new yet.", "example": true } } } } } }, "404": { "description": "Onboarding requisition not found, or the access token is missing or incorrect" } } } } }, "components": { "securitySchemes": {} }, "x-readme": { "explorer-enabled": false, "proxy-enabled": true, "samples-languages": [ "curl", "python", "javascript", "java", "go" ] } }