{ "openapi": "3.1.0", "info": { "title": "Zedy Gateway API", "summary": "Public API for Zedy Gateway whitelabel integrations.", "description": "Draft OpenAPI contract for the canonical /api/v1 surface. This document is pre-GA and tracks the Gateway Contract.", "version": "0.7.0-draft" }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "servers": [ { "url": "https://wl.zedy.com.br/api/v1", "description": "Production whitelabel domain" }, { "url": "http://localhost:3009/api/v1", "description": "Local development" } ], "tags": [ { "name": "Health" }, { "name": "Tokenization" }, { "name": "Charges" }, { "name": "Balance" }, { "name": "Receivables" }, { "name": "Settlements" } ], "paths": { "/health": { "get": { "tags": [ "Health" ], "operationId": "getHealth", "summary": "Check public API health.", "security": [], "responses": { "200": { "description": "Service is healthy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/payment-methods/tokenize": { "post": { "tags": [ "Tokenization" ], "operationId": "tokenizePaymentMethod", "summary": "Tokenize card data into a reusable payment method token.", "description": "This is the only public endpoint that accepts raw card data. PAN and CVV must not be persisted. Requires a seller-scoped API key and approved seller KYC; otherwise returns permission_error/seller_kyc_required.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "201": { "description": "Payment method token created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodTokenResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/PermissionError" }, "422": { "$ref": "#/components/responses/ValidationError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenizePaymentMethodRequest" }, "examples": { "card": { "value": { "card": { "number": "4242 4242 4242 4242", "exp_month": 12, "exp_year": 2030, "cvv": "123", "holder_name": "Ada Lovelace" } } } } } } } } }, "/charges": { "post": { "tags": [ "Charges" ], "operationId": "createCharge", "summary": "Create a charge.", "description": "Creates a charge using a tokenized payment method, Pix or boleto. For card charges, use capture_method=automatic to pay now or capture_method=manual to authorize now and capture later.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Charge created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/PermissionError" }, "409": { "$ref": "#/components/responses/IdempotencyError" }, "422": { "$ref": "#/components/responses/ValidationError" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChargeRequest" }, "examples": { "automaticCard": { "value": { "amount": 10990, "currency": "BRL", "payment_method": "CREDIT_CARD", "capture_method": "automatic", "card_token": "tok_xxx", "installments": 1, "buyer": { "name": "Ada Lovelace", "email": "ada@example.com", "phone": "+55 11 99999-0000", "document": "935.411.347-80", "ip": "203.0.113.10", "address": { "line_1": "Av. Paulista, 1000", "zip_code": "01310-100", "city": "Sao Paulo", "state": "SP", "country": "BR" } }, "metadata": { "order_id": "order_123" } } }, "manualCard": { "value": { "amount": 10990, "currency": "BRL", "payment_method": "CREDIT_CARD", "capture_method": "manual", "card_token": "tok_xxx", "installments": 1, "buyer": { "name": "Ada Lovelace", "email": "ada@example.com", "phone": "+55 11 99999-0000", "document": "935.411.347-80", "address": { "line_1": "Av. Paulista, 1000", "zip_code": "01310-100", "city": "Sao Paulo", "state": "SP", "country": "BR" } } } }, "pix": { "value": { "amount": 10990, "currency": "BRL", "payment_method": "PIX", "buyer": { "name": "Ada Lovelace", "email": "ada@example.com", "phone": "+55 11 99999-0000", "document": "935.411.347-80", "address": { "line_1": "Av. Paulista, 1000", "zip_code": "01310-100", "city": "Sao Paulo", "state": "SP", "country": "BR" } }, "pix": { "expires_in": 3600 } } } } } } } } }, "/charges/{id}": { "get": { "tags": [ "Charges" ], "operationId": "getCharge", "summary": "Retrieve a charge.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ChargeId" } ], "responses": { "200": { "description": "Charge found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/PermissionError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/charges/{id}/capture": { "post": { "tags": [ "Charges" ], "operationId": "captureCharge", "summary": "Capture an authorized charge.", "description": "Captures a card charge created with capture_method=manual and status=authorized.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ChargeId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Charge captured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/PermissionError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "$ref": "#/components/responses/IdempotencyError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/charges/{id}/refund": { "post": { "tags": [ "Refunds" ], "operationId": "refundCharge", "summary": "Refund a paid charge.", "description": "Refunds a paid or partially refunded charge. Omit amount_cents to refund the remaining balance.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ChargeId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundRequest" } } } }, "responses": { "201": { "description": "Refund created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/PermissionError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "$ref": "#/components/responses/IdempotencyError" }, "422": { "$ref": "#/components/responses/ValidationError" }, "502": { "description": "Payment provider unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/balance": { "get": { "tags": [ "Balance" ], "operationId": "getBalance", "summary": "Get the seller balance.", "description": "Returns pending, available, reserved and requestable balance for a seller-scoped API key. Requires permission balance:read and a seller-scoped key.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Seller balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/PermissionError" } } } }, "/balance/history": { "get": { "tags": [ "Balance" ], "operationId": "listBalanceHistory", "summary": "List the seller balance ledger history.", "description": "Lists tenant-scoped balance transactions (ledger entries) for a seller-scoped API key, most recent first. Requires permission balance:read and a seller-scoped key.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Balance transaction list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceTransactionListResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/PermissionError" } } } }, "/receivables": { "get": { "tags": [ "Receivables" ], "operationId": "listReceivables", "summary": "List receivables.", "description": "Lists tenant-scoped receivables. Requires permission receivables:read.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/ReceivableStatusFilter" } ], "responses": { "200": { "description": "Receivable list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivableListResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/PermissionError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/receivables/{id}": { "get": { "tags": [ "Receivables" ], "operationId": "getReceivable", "summary": "Get a receivable.", "description": "Returns a tenant-scoped receivable by public id. Requires permission receivables:read.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ReceivableId" } ], "responses": { "200": { "description": "Receivable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivableResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/PermissionError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/settlements": { "get": { "tags": [ "Settlements" ], "operationId": "listSettlements", "summary": "List settlements.", "description": "Lists tenant-scoped settlements. Requires permission settlements:read.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/SettlementStatusFilter" } ], "responses": { "200": { "description": "Settlement list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementListResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/PermissionError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/chargebacks": { "get": { "tags": [ "Chargebacks" ], "operationId": "listChargebacks", "summary": "List chargebacks.", "description": "Lists tenant-scoped chargebacks, most recent first (PSPFC-400). Requires permission chargebacks:read.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Chargeback list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargebackListResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/PermissionError" } } } }, "/chargebacks/{id}": { "get": { "tags": [ "Chargebacks" ], "operationId": "getChargeback", "summary": "Get a chargeback.", "description": "Returns a tenant-scoped chargeback by public id. Requires permission chargebacks:read.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ChargebackId" } ], "responses": { "200": { "description": "Chargeback.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargebackResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/PermissionError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/anticipations/simulate": { "post": { "tags": [ "Anticipations" ], "operationId": "simulateAnticipation", "summary": "Simulate anticipating not-yet-due receivables.", "description": "Pure preview, no side effects (PSPFC-700). Requires permission anticipations:read and a seller-scoped key. The anticipation price and D+N come from the whitelabel's commercial plan when set (seller override > default), otherwise from the seller's own anticipation config (WLPRC-110). The response echoes the resolved fee_bps_per_month, settlement_delay_days and pricing_plan_id.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "receivable_ids": { "type": "array", "items": { "type": "string", "pattern": "^recv_[A-Za-z0-9]+$" }, "minItems": 1, "maxItems": 100, "description": "Optional. Omit to simulate anticipating all eligible (PENDING, not yet anticipated) receivables." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Anticipation simulation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnticipationSimulationResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/PermissionError" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/anticipations": { "post": { "tags": [ "Anticipations" ], "operationId": "executeAnticipation", "summary": "Execute an anticipation.", "description": "Anticipates the seller's eligible receivables (PSPFC-700): cancels the original not-yet-due receivables and creates new ones immediately available for payout, net of the anticipation fee. Requires permission anticipations:create and a seller-scoped key.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "receivable_ids": { "type": "array", "items": { "type": "string", "pattern": "^recv_[A-Za-z0-9]+$" }, "minItems": 1, "maxItems": 100 } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Anticipation executed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnticipationResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/PermissionError" }, "409": { "$ref": "#/components/responses/IdempotencyError" }, "422": { "$ref": "#/components/responses/ValidationError" } } }, "get": { "tags": [ "Anticipations" ], "operationId": "listAnticipations", "summary": "List anticipations.", "description": "Lists tenant-scoped anticipations, most recent first. Requires permission anticipations:read and a seller-scoped key.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Anticipation list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnticipationListResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/PermissionError" } } } }, "/anticipations/{id}": { "get": { "tags": [ "Anticipations" ], "operationId": "getAnticipation", "summary": "Get an anticipation.", "description": "Returns a tenant-scoped anticipation by public id. Requires permission anticipations:read and a seller-scoped key.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ant_[A-Za-z0-9]+$" }, "example": "ant_xxx" } ], "responses": { "200": { "description": "Anticipation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnticipationResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/PermissionError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/settlements/{id}": { "get": { "tags": [ "Settlements" ], "operationId": "getSettlement", "summary": "Get a settlement.", "description": "Returns a tenant-scoped settlement by public id. Requires permission settlements:read.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/SettlementId" } ], "responses": { "200": { "description": "Settlement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationError" }, "403": { "$ref": "#/components/responses/PermissionError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "sk_test_ or sk_live_" } }, "parameters": { "ChargeId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$" }, "example": "ch_xxx" }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "example": "order_123_attempt_1" }, "ReceivableId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^recv_[A-Za-z0-9]+$" }, "example": "recv_xxx" }, "SettlementId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^set_[A-Za-z0-9]+$" }, "example": "set_xxx" }, "ChargebackId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cb_[A-Za-z0-9]+$" }, "example": "cb_xxx" }, "Page": { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "Limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "ReceivableStatusFilter": { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "available", "paid", "canceled", "anticipated" ] } }, "SettlementStatusFilter": { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "processing", "paid", "failed", "canceled" ] } } }, "responses": { "AuthenticationError": { "description": "Authentication failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "PermissionError": { "description": "API key lacks permission or scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFoundError": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "IdempotencyError": { "description": "Idempotency key conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ValidationError": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "RequestId": { "type": "string", "pattern": "^req_[A-Za-z0-9_\\-]+$", "examples": [ "req_xxx" ] }, "HealthResponse": { "type": "object", "required": [ "object", "service", "status", "version", "request_id" ], "properties": { "object": { "const": "health" }, "service": { "const": "zedy-gateway" }, "status": { "const": "ok" }, "version": { "const": "v1" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "additionalProperties": false }, "TokenizePaymentMethodRequest": { "type": "object", "required": [ "card" ], "properties": { "card": { "type": "object", "required": [ "number", "exp_month", "exp_year", "holder_name", "cvv" ], "properties": { "number": { "type": "string", "minLength": 12, "maxLength": 32 }, "exp_month": { "type": "integer", "minimum": 1, "maximum": 12 }, "exp_year": { "type": "integer", "minimum": 2026, "maximum": 2100 }, "cvv": { "type": "string", "pattern": "^[0-9]{3,4}$" }, "holder_name": { "type": "string", "minLength": 2, "maxLength": 120 } }, "additionalProperties": false }, "billing_address": { "type": "object", "properties": { "country": { "type": "string", "maxLength": 2 }, "zip_code": { "type": "string", "maxLength": 20 }, "state": { "type": "string", "maxLength": 80 }, "city": { "type": "string", "maxLength": 120 }, "line_1": { "type": "string", "maxLength": 160 }, "line_2": { "type": "string", "maxLength": 160 } }, "additionalProperties": false }, "metadata": { "type": "object", "additionalProperties": true } }, "additionalProperties": false }, "PaymentMethodTokenResponse": { "type": "object", "required": [ "id", "object", "type", "brand", "last4", "exp_month", "exp_year", "livemode", "request_id" ], "properties": { "id": { "type": "string", "pattern": "^tok_[A-Za-z0-9_\\-]+$" }, "object": { "const": "payment_method_token" }, "type": { "const": "card" }, "brand": { "type": "string" }, "last4": { "type": "string", "pattern": "^[0-9]{4}$" }, "exp_month": { "type": "integer", "minimum": 1, "maximum": 12 }, "exp_year": { "type": "integer" }, "livemode": { "type": "boolean" }, "environment": { "type": "string", "enum": [ "TEST", "LIVE" ] }, "seller_id": { "type": "string", "pattern": "^seller_[A-Za-z0-9_\\-]+$" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "additionalProperties": false }, "CreateChargeRequest": { "type": "object", "required": [ "amount", "payment_method", "buyer" ], "allOf": [ { "if": { "properties": { "payment_method": { "enum": [ "CREDIT_CARD", "DEBIT_CARD" ] } }, "required": [ "payment_method" ] }, "then": { "required": [ "card_token", "installments" ] } } ], "properties": { "amount": { "type": "integer", "minimum": 1, "description": "Amount in cents." }, "currency": { "const": "BRL", "default": "BRL" }, "payment_method": { "type": "string", "enum": [ "CREDIT_CARD", "DEBIT_CARD", "PIX", "BOLETO" ] }, "capture_method": { "type": "string", "enum": [ "automatic", "manual" ], "default": "automatic" }, "installments": { "type": "integer", "minimum": 1, "maximum": 24, "description": "Required for CREDIT_CARD and DEBIT_CARD. Send 1 for one-time card payments." }, "card_token": { "type": "string", "pattern": "^tok_[A-Za-z0-9_\\-]+$" }, "buyer": { "type": "object", "required": [ "name", "email", "phone", "document", "address" ], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 255 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "phone": { "type": "string", "description": "Buyer phone. Normalized to 10-15 digits by the API." }, "document": { "type": "string", "description": "Buyer CPF or CNPJ. The API validates check digits and stores digits only." }, "ip": { "type": "string", "description": "Buyer IPv4 or IPv6 address. If omitted, the API stores the request IP when available." }, "address": { "type": "object", "required": [ "line_1", "zip_code", "city", "state" ], "properties": { "line_1": { "type": "string", "minLength": 4, "maxLength": 220 }, "line_2": { "type": "string", "maxLength": 220 }, "zip_code": { "type": "string", "description": "Postal code. Validated as an 8-digit CEP when country is BR." }, "city": { "type": "string", "minLength": 2, "maxLength": 120 }, "state": { "type": "string", "minLength": 2, "maxLength": 80 }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code. Defaults to BR.", "default": "BR" } }, "additionalProperties": false } }, "additionalProperties": false }, "pix": { "type": "object", "properties": { "expires_in": { "type": "integer", "minimum": 60, "maximum": 86400 } }, "additionalProperties": false }, "boleto": { "type": "object", "properties": { "due_date": { "type": "string", "format": "date" } }, "additionalProperties": false }, "split": { "type": "array", "minItems": 1, "maxItems": 10, "description": "Optional split of the charge to other sellers of the same whitelabel (PSPFC-300). Recipients are carved out of the charge amount; the remainder stays with the charge's own seller through the normal fee/receivable flow. All items must use the same allocation mode (amount_cents or percentage_bps).", "items": { "type": "object", "required": [ "recipient_seller_id" ], "properties": { "recipient_seller_id": { "type": "string", "pattern": "^seller_[A-Za-z0-9]+$" }, "amount_cents": { "type": "integer", "minimum": 1 }, "percentage_bps": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "additionalProperties": false } }, "metadata": { "type": "object", "additionalProperties": true } }, "additionalProperties": false }, "ChargeResponse": { "type": "object", "required": [ "id", "object", "status", "amount_cents", "currency", "payment_method", "capture_method", "captured", "buyer", "created_at", "updated_at", "request_id" ], "properties": { "id": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$" }, "object": { "const": "charge" }, "status": { "type": "string", "enum": [ "pending", "authorized", "paid", "refused", "canceled", "refunded", "partially_refunded", "chargeback", "failed" ] }, "amount_cents": { "type": "integer", "minimum": 1 }, "currency": { "const": "BRL" }, "payment_method": { "type": "string", "enum": [ "credit_card", "debit_card", "pix", "boleto" ] }, "capture_method": { "type": "string", "enum": [ "automatic", "manual" ] }, "captured": { "type": "boolean" }, "installments": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 24 }, "buyer": { "type": "object", "required": [ "name", "email", "phone", "document", "document_type", "address" ], "properties": { "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "phone": { "type": [ "string", "null" ] }, "document": { "type": [ "string", "null" ] }, "document_type": { "type": [ "string", "null" ], "enum": [ "cpf", "cnpj", null ] }, "ip": { "type": [ "string", "null" ] }, "address": { "type": "object", "required": [ "line_1", "zip_code", "city", "state", "country" ], "properties": { "line_1": { "type": [ "string", "null" ] }, "line_2": { "type": [ "string", "null" ] }, "zip_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } }, "additionalProperties": false } }, "additionalProperties": false }, "acquirer_code": { "type": [ "string", "null" ] }, "acquirer_transaction_id": { "type": [ "string", "null" ] }, "authorization_code": { "type": [ "string", "null" ] }, "acquirer_return_code": { "type": [ "string", "null" ] }, "acquirer_return_message": { "type": [ "string", "null" ] }, "refused_reason": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "split": { "type": "array", "description": "Present only on GET /charges/{id} when the charge has splits applied (PSPFC-300). Only exposes the recipient and the gross amount allocated to them — fee/net details belong to the recipient's own balance/receivables.", "items": { "type": "object", "required": [ "recipient_seller_id", "amount_cents" ], "properties": { "recipient_seller_id": { "type": "string", "pattern": "^seller_[A-Za-z0-9]+$" }, "amount_cents": { "type": "integer", "minimum": 1 } }, "additionalProperties": false } }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "additionalProperties": false }, "RefundRequest": { "type": "object", "properties": { "amount_cents": { "type": "integer", "minimum": 1, "description": "Partial refund amount in cents. Omit to refund the remaining balance." }, "reason": { "type": "string", "minLength": 1, "maxLength": 120 } }, "additionalProperties": false }, "RefundResponse": { "type": "object", "required": [ "id", "object", "status", "charge_id", "amount_cents", "currency", "created_at", "updated_at", "request_id" ], "properties": { "id": { "type": "string", "pattern": "^rf_[A-Za-z0-9]+$" }, "object": { "const": "refund" }, "status": { "type": "string", "enum": [ "pending", "processing", "succeeded", "failed", "canceled" ] }, "charge_id": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$" }, "amount_cents": { "type": "integer", "minimum": 1 }, "currency": { "const": "BRL" }, "reason": { "type": [ "string", "null" ] }, "provider_reference": { "type": [ "string", "null" ] }, "succeeded_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "additionalProperties": false }, "BalanceResponse": { "type": "object", "required": [ "object", "pending_cents", "available_cents", "reserved_cents", "requestable_cents", "currency", "request_id" ], "properties": { "object": { "const": "balance" }, "pending_cents": { "type": "integer", "minimum": 0, "description": "Receivables not yet due (status pending)." }, "available_cents": { "type": "integer", "minimum": 0, "description": "Receivables released for payout (status available)." }, "reserved_cents": { "type": "integer", "minimum": 0, "description": "Available balance committed to in-flight payouts (pending_approval, approved, processing)." }, "requestable_cents": { "type": "integer", "minimum": 0, "description": "available_cents minus reserved_cents; what the seller can still request." }, "currency": { "const": "BRL" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "additionalProperties": false }, "BalanceTransactionResponse": { "type": "object", "required": [ "object", "id", "type", "direction", "amount_cents", "currency", "created_at" ], "properties": { "object": { "const": "balance_transaction" }, "id": { "type": "string", "pattern": "^ldge_[A-Za-z0-9]+$" }, "type": { "type": "string", "description": "Entry type, e.g. charge.sale, refund.succeeded, payout.paid." }, "direction": { "type": "string", "enum": [ "debit", "credit" ] }, "amount_cents": { "type": "integer", "minimum": 1 }, "currency": { "const": "BRL" }, "charge_id": { "type": [ "string", "null" ], "pattern": "^ch_[A-Za-z0-9]+$" }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "BalanceTransactionListResponse": { "type": "object", "required": [ "object", "data", "page", "limit", "total", "total_pages", "request_id" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BalanceTransactionResponse" } }, "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1 }, "total": { "type": "integer", "minimum": 0 }, "total_pages": { "type": "integer", "minimum": 0 }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "additionalProperties": false }, "ChargebackResponse": { "type": "object", "required": [ "object", "id", "charge_id", "amount_cents", "currency", "status", "opened_at", "created_at", "updated_at" ], "properties": { "object": { "const": "chargeback" }, "id": { "type": "string", "pattern": "^cb_[A-Za-z0-9]+$" }, "charge_id": { "type": "string", "pattern": "^ch_[A-Za-z0-9]+$" }, "amount_cents": { "type": "integer", "minimum": 1 }, "currency": { "const": "BRL" }, "status": { "type": "string", "enum": [ "open", "under_review", "won", "lost", "accepted" ] }, "reason_code": { "type": [ "string", "null" ] }, "evidence_due_at": { "type": [ "string", "null" ], "format": "date-time" }, "opened_at": { "type": "string", "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "ChargebackListResponse": { "type": "object", "required": [ "object", "data", "page", "limit", "total", "total_pages", "request_id" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChargebackResponse" } }, "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1 }, "total": { "type": "integer", "minimum": 0 }, "total_pages": { "type": "integer", "minimum": 0 }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "additionalProperties": false }, "AnticipationSimulationResponse": { "type": "object", "required": [ "object", "eligible_receivable_count", "gross_amount_cents", "fee_amount_cents", "net_amount_cents", "items", "exposure", "treasury", "request_id" ], "properties": { "object": { "const": "anticipation_simulation" }, "eligible_receivable_count": { "type": "integer", "minimum": 0 }, "gross_amount_cents": { "type": "integer", "minimum": 0 }, "fee_amount_cents": { "type": "integer", "minimum": 0 }, "net_amount_cents": { "type": "integer", "minimum": 0 }, "fee_bps_per_month": { "type": "integer", "minimum": 0, "description": "Resolved anticipation price in bps per month, pro-rata per day (WLPRC-110)." }, "settlement_delay_days": { "type": "integer", "minimum": 0, "description": "Anticipated settlement delay in days (D+N) in effect for this seller." }, "pricing_plan_id": { "type": [ "string", "null" ], "description": "Public id of the commercial plan that defined the anticipation terms, or null when using the seller's legacy config." }, "items": { "type": "array", "items": { "type": "object", "properties": { "gross_amount_cents": { "type": "integer", "minimum": 0 }, "fee_amount_cents": { "type": "integer", "minimum": 0 }, "net_amount_cents": { "type": "integer", "minimum": 0 }, "days_anticipated": { "type": "integer", "minimum": 0 } }, "additionalProperties": false } }, "exposure": { "type": "object", "required": [ "outstanding_cents", "projected_cents", "limit_cents", "available_cents", "within_limit" ], "properties": { "outstanding_cents": { "type": "integer", "minimum": 0 }, "projected_cents": { "type": "integer", "minimum": 0 }, "limit_cents": { "type": "integer", "minimum": 0 }, "available_cents": { "type": "integer", "minimum": 0 }, "within_limit": { "type": "boolean" } }, "additionalProperties": false }, "treasury": { "type": "object", "required": [ "available_cash_cents", "requested_cash_out_cents", "within_limit" ], "properties": { "available_cash_cents": { "type": "integer", "minimum": 0 }, "requested_cash_out_cents": { "type": "integer", "minimum": 0 }, "within_limit": { "type": "boolean" } }, "additionalProperties": false }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "additionalProperties": false }, "AnticipationResponse": { "type": "object", "required": [ "object", "id", "status", "gross_amount_cents", "fee_amount_cents", "net_amount_cents", "currency", "requested_at", "created_at", "updated_at" ], "properties": { "object": { "const": "anticipation" }, "id": { "type": "string", "pattern": "^ant_[A-Za-z0-9]+$" }, "status": { "type": "string", "enum": [ "requested", "approved", "rejected", "executed", "canceled" ] }, "fee_bps_per_month": { "type": "integer", "minimum": 0 }, "pricing_plan_id": { "type": [ "string", "null" ], "description": "Public id of the commercial plan whose anticipation terms priced this anticipation (WLPRC-110). Null when priced from the seller's legacy config." }, "gross_amount_cents": { "type": "integer", "minimum": 0 }, "fee_amount_cents": { "type": "integer", "minimum": 0 }, "net_amount_cents": { "type": "integer", "minimum": 0 }, "currency": { "const": "BRL" }, "requested_at": { "type": "string", "format": "date-time" }, "executed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "AnticipationListResponse": { "type": "object", "required": [ "object", "data", "request_id" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AnticipationResponse" } }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "additionalProperties": false }, "ReceivableResponse": { "type": "object", "required": [ "object", "id", "amount_cents", "currency", "status", "expected_date", "created_at", "updated_at", "request_id" ], "properties": { "object": { "const": "receivable" }, "id": { "type": "string", "pattern": "^recv_[A-Za-z0-9]+$" }, "charge_id": { "type": [ "string", "null" ], "pattern": "^ch_[A-Za-z0-9]+$" }, "amount_cents": { "type": "integer", "minimum": 1 }, "gross_amount_cents": { "type": "integer", "minimum": 0 }, "fee_amount_cents": { "type": "integer", "minimum": 0 }, "installment": { "type": "integer", "minimum": 1 }, "installment_count": { "type": "integer", "minimum": 1 }, "origin": { "type": "string", "enum": [ "sale", "refund_adjustment", "chargeback_adjustment", "anticipation", "manual_adjustment" ] }, "currency": { "const": "BRL" }, "status": { "type": "string", "enum": [ "pending", "available", "paid", "canceled", "anticipated" ] }, "expected_date": { "type": "string", "format": "date-time" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "additionalProperties": false }, "ReceivableListResponse": { "type": "object", "required": [ "object", "data", "page", "limit", "total", "total_pages", "request_id" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReceivableResponse" } }, "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1 }, "total": { "type": "integer", "minimum": 0 }, "total_pages": { "type": "integer", "minimum": 0 }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "additionalProperties": false }, "SettlementResponse": { "type": "object", "required": [ "object", "id", "amount_cents", "currency", "status", "created_at", "updated_at", "request_id" ], "properties": { "object": { "const": "settlement" }, "id": { "type": "string", "pattern": "^set_[A-Za-z0-9]+$" }, "payout_request_id": { "type": [ "string", "null" ], "pattern": "^payout_[A-Za-z0-9]+$" }, "amount_cents": { "type": "integer", "minimum": 1 }, "currency": { "const": "BRL" }, "status": { "type": "string", "enum": [ "pending", "processing", "paid", "failed", "canceled" ] }, "bank_export_format": { "type": [ "string", "null" ], "enum": [ "ofx", "cnab240", null ] }, "bank_export_generated_at": { "type": [ "string", "null" ], "format": "date-time" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "additionalProperties": false }, "SettlementListResponse": { "type": "object", "required": [ "object", "data", "page", "limit", "total", "total_pages", "request_id" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SettlementResponse" } }, "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1 }, "total": { "type": "integer", "minimum": 0 }, "total_pages": { "type": "integer", "minimum": 0 }, "request_id": { "$ref": "#/components/schemas/RequestId" } }, "additionalProperties": false }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "request_id" ], "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "validation_error", "idempotency_error", "not_found_error", "rate_limit_error", "configuration_error", "api_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "$ref": "#/components/schemas/RequestId" }, "issues": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": false } }, "additionalProperties": false } } } }