{ "openapi": "3.1.0", "info": { "title": "RenkoPay Gateway API", "version": "2.3.0", "summary": "API multitenant para pagamentos, links, transações, recebedores, split e webhooks.", "description": "Especificação pública consolidada do RenkoPay Gateway. Todas as operações protegidas são tenant-scoped pelo token Bearer. Erros HTTP 409 e 422 representam recusas definitivas de negócio e não devem receber retry automático; erros 5xx devem ser tratados como falhas técnicas/transitórias. Os webhooks enviados ao cliente são assinados por HMAC SHA-256 e devem receber resposta HTTP 2xx. O endpoint POST /api/v1/transactions/{id}/sync-provider usa sempre o public_id UUID da RenkoPay. Identificadores internos da adquirente não devem ser enviados pelo integrador.", "contact": { "name": "RenkoPay Tecnologia" } }, "servers": [ { "url": "https://gateway.renkopay.com.br", "description": "Produção" } ], "tags": [ { "name": "Health", "description": "Disponibilidade da API." }, { "name": "Autenticação", "description": "Emissão do Bearer token do tenant." }, { "name": "Pagadores", "description": "CRUD de clientes, pagadores e sacados. Dados sensíveis ficam cifrados; cartão nunca é armazenado." }, { "name": "Payment Links", "description": "Links de pagamento hospedados com valor fixo ou informado pelo pagador." }, { "name": "PIX", "description": "Criação e consulta de cobranças PIX." }, { "name": "Boleto", "description": "Criação, consulta e PDF de boleto." }, { "name": "Cartão", "description": "Crédito e débito com 3DS, inclusive fluxo server-to-server." }, { "name": "Transações", "description": "Consulta, cancelamento, estorno, captura e sincronização com adquirente." }, { "name": "Split PIX", "description": "Regras de split por tenant." }, { "name": "Adquirente, Cobranças", "description": "Operações avançadas tenant-scoped diretamente vinculadas ao seller Adquirente." }, { "name": "Adquirente, Faturas", "description": "Faturas e recorrência Adquirente." }, { "name": "Adquirente, Assinaturas", "description": "Subscriptions Adquirente." }, { "name": "Adquirente, Conta e Recebíveis", "description": "Saldo, transferências, ajustes e recebíveis do seller." }, { "name": "Webhooks", "description": "Endpoints técnicos de entrada de eventos de adquirentes." }, { "name": "Hosted Checkout", "description": "Checkout hospedado white-label. O branding é resolvido pelo tenant; sem personalização, aplica-se o tema padrão RenkoPay Gateway." }, { "name": "High Performance", "description": "Recursos de operação em alto volume, health checks, idempotência e processamento assíncrono." }, { "name": "Webhooks enviados ao cliente", "description": "Contrato dos eventos outbound enviados aos endpoints configurados pelo tenant." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "RenkoPay access token", "description": "Token emitido por POST /api/v1/auth/token." } }, "schemas": { "AuthTokenRequest": { "type": "object", "required": [ "client_id", "client_secret" ], "properties": { "client_id": { "type": "string", "format": "uuid" }, "client_secret": { "type": "string", "minLength": 20 } } }, "AuthTokenResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "example": "Bearer" }, "expires_at": { "type": "string", "format": "date-time" }, "expires_in": { "type": "number", "example": 1800 } } }, "Customer": { "type": "object", "required": [ "name", "document" ], "properties": { "name": { "type": "string", "maxLength": 150 }, "document": { "type": "string", "maxLength": 20 }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "maxLength": 30 }, "birthdate": { "type": "string", "format": "date" }, "address": { "$ref": "#/components/schemas/CustomerAddress" } } }, "PixChargeRequest": { "type": "object", "required": [ "amount", "customer" ], "properties": { "external_id": { "type": "string", "maxLength": 100 }, "amount": { "type": "number", "minimum": 0.01 }, "description": { "type": "string" }, "expires_in": { "type": "integer", "minimum": 60, "maximum": 86400 }, "split_rule_id": { "type": "string", "format": "uuid" }, "customer": { "$ref": "#/components/schemas/PixCustomer" }, "metadata": { "type": "object", "additionalProperties": true }, "receiver_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Recebedor único. O restante após a comissão do tenant é destinado a ele." }, "receivers": { "type": [ "array", "null" ], "description": "Rateio entre múltiplos recebedores. Percentuais somam 100% do valor restante após a comissão.", "items": { "type": "object", "properties": { "receiver_id": { "type": "string", "format": "uuid" }, "percentage": { "type": "number" }, "amount": { "type": "number" }, "absorb_fee": { "type": "boolean" } } } } }, "example": { "external_id": "pedido-1001", "amount": 150.75, "description": "Pedido 1001", "expires_in": 3600, "customer": { "name": "João da Silva", "document": "12345678901", "email": "joao@email.com", "phone": "11999999999", "birthdate": "1990-01-01" }, "metadata": { "pedido_id": 1001, "origem": "ecommerce" } } }, "BoletoChargeRequest": { "type": "object", "required": [ "amount", "due_date", "customer" ], "properties": { "external_id": { "type": "string" }, "amount": { "type": "number", "minimum": 0.01 }, "due_date": { "type": "string", "format": "date" }, "description": { "type": "string" }, "customer": { "$ref": "#/components/schemas/BoletoCustomer" }, "metadata": { "type": "object", "additionalProperties": true }, "payment_limit_date": { "type": "string", "format": "date", "description": "Deve ser posterior a due_date." }, "document_number": { "type": "string", "maxLength": 32 }, "our_number": { "type": "string", "minLength": 5, "maxLength": 15 }, "instructions": { "type": "string", "maxLength": 255 }, "receiver_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Recebedor único. O restante após a comissão do tenant é destinado a ele." }, "receivers": { "type": [ "array", "null" ], "description": "Rateio entre múltiplos recebedores. Percentuais somam 100% do valor restante após a comissão.", "items": { "type": "object", "properties": { "receiver_id": { "type": "string", "format": "uuid" }, "percentage": { "type": "number" }, "amount": { "type": "number" }, "absorb_fee": { "type": "boolean" } } } } }, "example": { "external_id": "pedido-1003", "amount": 299.9, "due_date": "2026-12-10", "payment_limit_date": "2026-12-15", "description": "Pedido 1003", "instructions": "Não receber após a data limite.", "customer": { "name": "Maria Souza", "document": "12345678901", "email": "maria@example.com", "phone": "11999999999", "birthdate": "1990-01-01", "address": { "street": "Avenida Rio Verde", "number": "SN", "neighborhood": "Vila São Tomaz", "city": "Aparecida de Goiânia", "state": "GO", "zip_code": "74915515" } }, "metadata": { "pedido_id": 1003 } } }, "PixSplitDestination": { "type": "object", "required": [ "label", "destination_type", "percentage" ], "properties": { "label": { "type": "string" }, "destination_type": { "type": "string", "enum": [ "PIX_KEY", "BANK_ACCOUNT", "DTVM_ACCOUNT" ] }, "percentage": { "type": "number", "minimum": 0.0001, "maximum": 100 }, "pix_key_type": { "type": "string" }, "pix_key": { "type": "string" }, "dtvm_account_id": { "type": "string" }, "ispb": { "type": "string" }, "bank_code": { "type": "string" }, "branch": { "type": "string" }, "account_number": { "type": "string" }, "account_digit": { "type": "string" }, "account_type": { "type": "string" }, "document": { "type": "string" }, "name": { "type": "string" }, "receiver_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Recebedor único. O restante após a comissão do tenant é destinado a ele." }, "receivers": { "type": [ "array", "null" ], "description": "Rateio entre múltiplos recebedores. Percentuais somam 100% do valor restante após a comissão.", "items": { "type": "object", "properties": { "receiver_id": { "type": "string", "format": "uuid" }, "percentage": { "type": "number" }, "amount": { "type": "number" }, "absorb_fee": { "type": "boolean" } } } } } }, "PixSplitRuleRequest": { "type": "object", "required": [ "name", "apply_mode", "destinations" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "apply_mode": { "type": "string", "enum": [ "MANUAL", "ALL_PIX" ] }, "priority": { "type": "integer", "default": 100 }, "destinations": { "type": "array", "items": { "$ref": "#/components/schemas/PixSplitDestination" } }, "receiver_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Recebedor único. O restante após a comissão do tenant é destinado a ele." }, "receivers": { "type": [ "array", "null" ], "description": "Rateio entre múltiplos recebedores. Percentuais somam 100% do valor restante após a comissão.", "items": { "type": "object", "properties": { "receiver_id": { "type": "string", "format": "uuid" }, "percentage": { "type": "number" }, "amount": { "type": "number" }, "absorb_fee": { "type": "boolean" } } } } } }, "PaymentTransaction": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "public_id UUID da transação RenkoPay. Use este valor nas operações da API." }, "external_id": { "type": "string" }, "method": { "type": "string", "enum": [ "PIX", "BOLETO", "CARD" ] }, "status": { "type": "string", "description": "Status normalizado RenkoPay. UNKNOWN indica que o estado ainda não pôde ser confirmado junto ao provedor." }, "amount": { "type": "number" }, "currency": { "type": "string", "example": "BRL" }, "customer": { "$ref": "#/components/schemas/Customer" }, "pix": { "type": "object" }, "boleto": { "type": "object" }, "split": { "type": "object" }, "provider": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Error": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object" } } }, "CustomerAddress": { "type": "object", "required": [ "street", "neighborhood", "city", "state", "zip_code" ], "properties": { "street": { "type": "string", "maxLength": 120 }, "number": { "type": "string", "maxLength": 20, "description": "Obrigatório quando street_number não for enviado." }, "street_number": { "type": "string", "maxLength": 20, "description": "Obrigatório quando number não for enviado." }, "complement": { "type": "string", "maxLength": 120 }, "neighborhood": { "type": "string", "maxLength": 80 }, "city": { "type": "string", "maxLength": 80 }, "state": { "type": "string", "minLength": 2, "maxLength": 2, "example": "GO" }, "zip_code": { "type": "string", "maxLength": 12, "example": "74915515" }, "country": { "type": "string", "example": "BR" } } }, "PixCustomer": { "allOf": [ { "$ref": "#/components/schemas/Customer" } ], "required": [ "name", "document", "birthdate" ], "description": "Para PIX, birthdate é obrigatório na API atual." }, "BoletoCustomer": { "allOf": [ { "$ref": "#/components/schemas/Customer" } ], "required": [ "name", "document", "address" ], "description": "Para boleto, address é obrigatório. Dentro do endereço, informe number ou street_number." }, "CardChargeRequest": { "type": "object", "required": [ "amount", "customer", "card" ], "properties": { "external_id": { "type": "string", "maxLength": 100 }, "amount": { "type": "number", "minimum": 0.01 }, "description": { "type": "string", "maxLength": 255 }, "card_operation": { "type": "string", "enum": [ "CREDIT", "DEBIT", "CREDIT_CARD", "DEBIT_CARD" ] }, "customer": { "$ref": "#/components/schemas/Customer" }, "card": { "type": "object", "required": [ "holder_name", "number", "expiration_month", "expiration_year", "cvv" ], "properties": { "holder_name": { "type": "string" }, "number": { "type": "string" }, "expiration_month": { "type": "string" }, "expiration_year": { "type": "string" }, "cvv": { "type": "string" }, "installments": { "type": "integer", "minimum": 1, "maximum": 24 }, "capture": { "type": "boolean" }, "token": { "type": "string" } } }, "metadata": { "type": "object", "additionalProperties": true }, "receiver_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Recebedor único. O restante após a comissão do tenant é destinado a ele." }, "receivers": { "type": [ "array", "null" ], "description": "Rateio entre múltiplos recebedores. Percentuais somam 100% do valor restante após a comissão.", "items": { "type": "object", "properties": { "receiver_id": { "type": "string", "format": "uuid" }, "percentage": { "type": "number" }, "amount": { "type": "number" }, "absorb_fee": { "type": "boolean" } } } } }, "description": "Pagamento server-to-server com 3DS obrigatório para Adquirente. PAN/CVV são usados somente durante o request e não devem ser persistidos pelo integrador RenkoPay.", "examples": [ { "external_id": "pedido-12345", "amount": 149.9, "card_operation": "CREDIT", "description": "Pedido #12345", "customer": { "name": "Maria da Silva", "document": "12345678909", "email": "maria@example.com", "phone": "+5562999999999", "address": { "street": "Rua Exemplo", "number": "100", "neighborhood": "Centro", "city": "Goiânia", "state": "GO", "zip_code": "74000000" } }, "card": { "holder_name": "MARIA DA SILVA", "number": "4111111111111111", "expiration_month": "12", "expiration_year": "2030", "cvv": "123", "installments": 1 }, "three_ds": { "screen_width": 1920, "screen_height": 1080, "color_depth": 24, "java_enabled": false, "javascript_enabled": true, "language": "pt-BR", "time_zone_offset": -3, "ip_address": "177.0.0.1", "user_agent": "Mozilla/5.0", "success_url": "https://merchant.example.com/3ds/success", "failure_url": "https://merchant.example.com/3ds/failure" } } ] }, "PaymentLinkCreateRequest": { "type": "object", "required": [ "title" ], "properties": { "external_id": { "type": "string", "example": "pedido-link-1001" }, "title": { "type": "string", "maxLength": 160, "description": "Título obrigatório do link.", "example": "Pedido 1001" }, "description": { "type": "string", "example": "Checkout hospedado com PIX, boleto e cartão" }, "amount": { "type": "number", "format": "float", "example": 150.0, "description": "Obrigatório apenas para link de valor fixo. Em link com allow_customer_amount=true, use suggested_amount/minimum_amount/maximum_amount." }, "amount_mode": { "type": "string", "enum": [ "fixed", "customer" ], "description": "Campo auxiliar usado pelo gerencial. Para API, prefira allow_customer_amount." }, "allow_customer_amount": { "type": "boolean", "default": false, "description": "Quando true, o pagador informa o valor no checkout público." }, "suggested_amount": { "type": "number", "format": "float", "nullable": true, "example": 150.0, "description": "Valor sugerido exibido no checkout quando allow_customer_amount=true." }, "minimum_amount": { "type": "number", "format": "float", "nullable": true, "example": 10.0, "description": "Valor mínimo aceito no checkout quando allow_customer_amount=true." }, "maximum_amount": { "type": "number", "format": "float", "nullable": true, "example": 5000.0, "description": "Valor máximo aceito no checkout quando allow_customer_amount=true." }, "currency": { "type": "string", "example": "BRL" }, "allowed_methods": { "type": "array", "items": { "type": "string", "enum": [ "PIX", "BOLETO", "CARD", "CREDIT_CARD", "DEBIT_CARD" ] }, "example": [ "PIX", "BOLETO", "CARD" ] }, "default_method": { "type": "string", "enum": [ "PIX", "BOLETO", "CARD", "CREDIT_CARD", "DEBIT_CARD" ], "example": "PIX" }, "due_date": { "type": "string", "format": "date", "example": "2026-12-10" }, "expires_at": { "type": "string", "format": "date-time", "example": "2026-12-20T23:59:59-03:00" }, "max_payments": { "type": "integer", "example": 1 }, "success_url": { "type": "string", "format": "uri" }, "cancel_url": { "type": "string", "format": "uri" }, "customer": { "type": "object", "properties": { "name": { "type": "string", "example": "João da Silva" }, "document": { "type": "string", "example": "12345678901" }, "email": { "type": "string", "format": "email", "example": "joao@email.com" }, "phone": { "type": "string", "example": "11999999999" }, "birthdate": { "type": "string", "format": "date", "example": "1990-01-01" }, "address": { "type": "object", "properties": { "street": { "type": "string", "example": "Avenida Rio Verde" }, "number": { "type": "string", "example": "SN" }, "neighborhood": { "type": "string", "example": "Vila São Tomaz" }, "city": { "type": "string", "example": "Aparecida de Goiânia" }, "state": { "type": "string", "example": "GO" }, "zip_code": { "type": "string", "example": "74915515" } } } } }, "metadata": { "type": "object", "additionalProperties": true, "example": { "order_id": "1001" } }, "payer_id": { "type": [ "string", "null" ], "format": "uuid", "description": "ID público do pagador cadastrado no mesmo tenant. Quando informado, os dados cadastrais são lidos do cadastro cifrado e usados no checkout." }, "receiver_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Recebedor único. O restante após a comissão do tenant é destinado a ele." }, "receivers": { "type": [ "array", "null" ], "description": "Rateio entre múltiplos recebedores. Percentuais somam 100% do valor restante após a comissão.", "items": { "type": "object", "properties": { "receiver_id": { "type": "string", "format": "uuid" }, "percentage": { "type": "number" }, "amount": { "type": "number" }, "absorb_fee": { "type": "boolean" } } } }, "settings": { "type": [ "object", "null" ], "additionalProperties": true } } }, "PaymentLinkResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string" }, "tenant_id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "amount_type": { "type": "string", "enum": [ "FIXED", "CUSTOMER_DEFINED" ] }, "amount": { "type": "number", "format": "float", "nullable": true, "description": "Valor fixo do link. Retorna null quando o link usa valor informado pelo pagador." }, "allow_customer_amount": { "type": "boolean" }, "suggested_amount": { "type": "number", "format": "float", "nullable": true }, "minimum_amount": { "type": "number", "format": "float", "nullable": true }, "maximum_amount": { "type": "number", "format": "float", "nullable": true }, "currency": { "type": "string" }, "allowed_methods": { "type": "array", "items": { "type": "string" } }, "default_method": { "type": "string" }, "status": { "type": "string" }, "checkout_url": { "type": "string", "format": "uri" }, "due_date": { "type": "string", "format": "date", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "max_payments": { "type": "integer" }, "paid_count": { "type": "integer" }, "customer": { "type": "object", "nullable": true }, "metadata": { "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "payer_id": { "type": [ "string", "null" ], "format": "uuid" }, "receiver_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Recebedor único. O restante após a comissão do tenant é destinado a ele." }, "receivers": { "type": [ "array", "null" ], "description": "Rateio entre múltiplos recebedores. Percentuais somam 100% do valor restante após a comissão.", "items": { "type": "object", "properties": { "receiver_id": { "type": "string", "format": "uuid" }, "percentage": { "type": "number" }, "amount": { "type": "number" }, "absorb_fee": { "type": "boolean" } } } }, "transactions": { "type": "array", "description": "Presente no GET de detalhe. Contém até as 20 transações mais recentes vinculadas ao link.", "items": { "$ref": "#/components/schemas/PaymentLinkTransactionSummary" } }, "success_url": { "type": [ "string", "null" ], "format": "uri" }, "cancel_url": { "type": [ "string", "null" ], "format": "uri" }, "settings": { "type": [ "object", "null" ], "additionalProperties": true }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "example": { "id": "b0c017aa-60bc-4d99-a23c-b23050e25d82", "external_id": "pedido-link-1001", "title": "Pedido 1001", "amount": 150.0, "currency": "BRL", "allowed_methods": [ "PIX", "BOLETO", "CARD" ], "default_method": "PIX", "status": "ACTIVE", "checkout_url": "https://gateway.renkopay.com.br/pay/b0c017aa-60bc-4d99-a23c-b23050e25d82", "amount_type": "FIXED", "allow_customer_amount": false, "suggested_amount": null, "minimum_amount": null, "maximum_amount": null } }, "Payer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "external_id": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "PERSON", "COMPANY" ] }, "name": { "type": "string" }, "document": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "phone": { "type": [ "string", "null" ] }, "birthdate": { "type": [ "string", "null" ], "format": "date" }, "pix_key_type": { "type": [ "string", "null" ], "enum": [ "CPF", "CNPJ", "EMAIL", "PHONE", "EVP", "OTHER", null ] }, "pix_key": { "type": [ "string", "null" ] }, "address": { "oneOf": [ { "$ref": "#/components/schemas/CustomerAddress" }, { "type": "null" } ] }, "notes": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "is_active": { "type": "boolean" } } }, "PayerUpsertRequest": { "type": "object", "required": [ "type", "name" ], "properties": { "external_id": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "PERSON", "COMPANY" ] }, "name": { "type": "string" }, "document": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "phone": { "type": [ "string", "null" ] }, "birthdate": { "type": [ "string", "null" ], "format": "date" }, "pix_key_type": { "type": [ "string", "null" ], "enum": [ "CPF", "CNPJ", "EMAIL", "PHONE", "EVP", "OTHER", null ] }, "pix_key": { "type": [ "string", "null" ] }, "address": { "oneOf": [ { "$ref": "#/components/schemas/CustomerAddress" }, { "type": "null" } ] }, "notes": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "is_active": { "type": "boolean" } } }, "ValidationError": { "type": "object", "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message" ] }, "CancelRequest": { "type": "object", "properties": { "notes": { "type": [ "string", "null" ], "maxLength": 2000, "example": "Solicitado pelo lojista" } } }, "RefundRequest": { "type": "object", "description": "Solicitação de estorno/reembolso. Para PIX na integração atual, a devolução suportada é TOTAL: envie `scope: TOTAL` e omita `amount`. Enviar `scope: PARTIAL` ou um `amount` menor que o saldo reembolsável retorna HTTP 422 com `PIX_PARTIAL_REFUND_UNSUPPORTED`. Para cartão, TOTAL/PARTIAL permanecem disponíveis conforme capacidade do provedor.", "properties": { "scope": { "type": [ "string", "null" ], "enum": [ "TOTAL", "PARTIAL", null ], "default": "TOTAL", "description": "TOTAL ou PARTIAL. Para PIX na integração atual use TOTAL." }, "amount": { "type": [ "number", "null" ], "format": "double", "minimum": 0.01, "description": "Valor do estorno parcial quando suportado. Para PIX TOTAL, omita este campo." }, "reason": { "type": [ "string", "null" ], "enum": [ "DUPLICATE_CHARGE", "IMPROPER_CHARGE", "COSTUMER_WITHDRAWAL", "OTHERS", null ] }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 } }, "examples": [ { "scope": "TOTAL", "notes": "Devolução integral solicitada pelo cliente" }, { "scope": "PARTIAL", "amount": 25.5, "reason": "OTHERS", "notes": "Exemplo aplicável apenas a métodos/provedores que suportem parcial" } ] }, "AdjustmentResponse": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": true } }, "required": [ "data" ] }, "ProviderOperationResponse": { "type": "object", "properties": { "successful": { "type": "boolean" }, "status": { "type": "integer" }, "body": { "type": "object", "additionalProperties": true }, "headers": { "type": "object", "additionalProperties": true }, "error": { "type": [ "string", "null" ] } }, "required": [ "successful", "status" ] }, "AcquirerProxyResponse": { "type": "object", "properties": { "successful": { "type": "boolean" }, "status": { "type": "integer" }, "body": { "type": "object", "additionalProperties": true }, "headers": { "type": "object", "additionalProperties": true }, "error": { "type": [ "string", "null" ] } }, "required": [ "successful", "status" ] }, "AcquirerSplitRequest": { "type": "object", "properties": { "splits": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": true } } }, "required": [ "splits" ] }, "FreeFormProviderPayload": { "type": "object", "description": "Payload repassado para a operação Adquirente correspondente. Consulte os campos suportados no manual operacional RenkoPay/Adquirente.", "additionalProperties": true }, "ThreeDSAction": { "type": "object", "properties": { "required": { "type": "boolean" }, "challenge_url": { "type": [ "string", "null" ], "format": "uri" }, "authentication_transaction_id": { "type": [ "string", "null" ] }, "transaction_id": { "type": [ "string", "null" ] }, "acs_url": { "type": [ "string", "null" ], "format": "uri" }, "validate_url": { "type": [ "string", "null" ], "format": "uri" }, "status": { "type": [ "string", "null" ] } } }, "PaginationMeta": { "type": "object", "additionalProperties": true }, "Receiver": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "external_id": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "PERSON", "COMPANY" ] }, "role": { "type": "string", "enum": [ "PAYEE", "COMMISSION" ] }, "name": { "type": "string" }, "document": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "pix_key_type": { "type": [ "string", "null" ] }, "pix_key": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "kyc_status": { "type": "string" }, "provider_ready": { "type": "boolean" } } }, "ReceiverUpsertRequest": { "type": "object", "required": [ "type", "name", "document", "email", "phone", "address", "bank_account" ], "properties": { "external_id": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "PERSON", "COMPANY" ] }, "role": { "type": "string", "enum": [ "PAYEE", "COMMISSION" ], "default": "PAYEE" }, "name": { "type": "string" }, "document": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "birthdate": { "type": [ "string", "null" ], "format": "date" }, "address": { "type": "object" }, "bank_account": { "type": "object", "description": "Conta de liquidação do recebedor. Armazenada cifrada." }, "pix_key_type": { "type": [ "string", "null" ] }, "pix_key": { "type": [ "string", "null" ], "description": "Chave PIX de referência da conta, armazenada cifrada." }, "sync_provider": { "type": "boolean", "default": true } } }, "ReceiverSplitSettings": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "commission_percentage": { "type": "number", "format": "double" }, "commission_receiver_id": { "type": [ "string", "null" ], "format": "uuid" }, "commission_absorb_fee": { "type": "boolean" } } }, "BusinessRuleError": { "type": "object", "required": [ "message", "code" ], "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "TRANSACTION_STATE_CONFLICT", "TRANSACTION_ACTION_INVALID" ] } }, "examples": [ { "message": "Reembolso/estorno é permitido apenas para transações pagas ou autorizadas/pendentes.", "code": "TRANSACTION_STATE_CONFLICT" }, { "message": "Operação não suportada ou parâmetros inválidos.", "code": "TRANSACTION_ACTION_INVALID" } ] }, "PaymentLinkTransactionSummary": { "type": "object", "required": [ "id", "method", "status", "amount", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "public_id da transação." }, "external_id": { "type": [ "string", "null" ] }, "method": { "type": [ "string", "null" ], "enum": [ "PIX", "BOLETO", "CARD", "CREDIT_CARD", "DEBIT_CARD", null ] }, "status": { "type": [ "string", "null" ] }, "amount": { "type": "number", "format": "double" }, "provider": { "type": [ "string", "null" ] }, "provider_status": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ClientWebhookData": { "type": "object", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string" }, "external_id": { "type": [ "string", "null" ] }, "acquirer_external_id": { "type": [ "string", "null" ] }, "audit_correlation_id": { "type": [ "string", "null" ], "format": "uuid" }, "method": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "amount": { "type": "number", "format": "double" }, "currency": { "type": "string", "example": "BRL" }, "provider": { "type": [ "string", "null" ] }, "provider_transaction_id": { "type": [ "string", "null" ] }, "provider_status": { "type": [ "string", "null" ] }, "provider_normalized_payload": { "type": [ "object", "null" ], "additionalProperties": true }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "failed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ClientWebhookPayload": { "type": "object", "required": [ "event", "id", "created_at", "data" ], "properties": { "event": { "type": "string", "example": "payment.pix.paid" }, "id": { "type": "string", "format": "uuid", "description": "Identificador único da entrega/evento." }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/ClientWebhookData" } } }, "WebhookHeaders": { "type": "object", "description": "Headers enviados pelo Gateway.", "properties": { "X-Gateway-Event": { "type": "string" }, "X-Gateway-Delivery": { "type": "string", "format": "uuid" }, "X-Gateway-Signature": { "type": "string", "example": "t=1700000000,v1=..." }, "X-Gateway-Tenant": { "type": "string" }, "X-Gateway-Transaction": { "type": "string", "format": "uuid" } } }, "TransactionSyncResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "id", "previous_status", "status", "reconciled", "synchronized_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "public_id da transação RenkoPay." }, "external_id": { "type": [ "string", "null" ] }, "previous_status": { "type": "string", "example": "UNKNOWN" }, "status": { "type": "string", "example": "PAID" }, "provider_status": { "type": [ "string", "null" ], "example": "PAID" }, "reconciled": { "type": "boolean", "example": true }, "synchronized_at": { "type": "string", "format": "date-time" } } } } }, "ProviderReferenceUnresolvedError": { "type": "object", "required": [ "message", "code" ], "properties": { "message": { "type": "string", "example": "Não foi possível resolver a referência interna da cobrança para sincronização." }, "code": { "type": "string", "example": "PROVIDER_REFERENCE_UNRESOLVED" } } }, "PixPartialRefundUnsupportedError": { "type": "object", "required": [ "message", "code" ], "properties": { "message": { "type": "string", "example": "Estorno parcial de PIX não é suportado pela integração atual. Para devolver o PIX, utilize scope TOTAL sem amount." }, "code": { "type": "string", "const": "PIX_PARTIAL_REFUND_UNSUPPORTED" } } }, "ProviderRefundRejectedAdjustment": { "type": "object", "description": "Exemplo de ajuste criado, mas recusado pelo provedor sem movimentação financeira local.", "properties": { "data": { "type": "object", "properties": { "action": { "type": "string", "example": "REFUND" }, "scope": { "type": "string", "example": "TOTAL" }, "status": { "type": "string", "example": "FAILED" }, "provider_status": { "type": [ "string", "null" ], "example": null }, "http_status": { "type": [ "integer", "null" ], "example": 404 }, "error_message": { "type": [ "string", "null" ], "example": "Estorno temporariamente indisponível para esta cobrança." }, "response_payload": { "type": "object", "additionalProperties": true, "example": { "code": "404", "message": "Estorno temporariamente indisponível para esta cobrança." } } } } } } } }, "paths": { "/api/health": { "get": { "tags": [ "Health" ], "summary": "Health check", "responses": { "200": { "description": "API online" } }, "security": [] } }, "/api/v1/auth/token": { "post": { "tags": [ "Autenticação" ], "summary": "Gerar bearer token", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTokenRequest" } } } }, "responses": { "200": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTokenResponse" } } } }, "401": { "description": "Credenciais inválidas", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "IP não autorizado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "createAccessToken", "security": [] } }, "/api/v1/pix/charges": { "post": { "tags": [ "PIX" ], "summary": "Emitir cobrança PIX", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixChargeRequest" }, "example": { "external_id": "pedido-1001", "amount": 150.75, "description": "Pedido 1001", "expires_in": 3600, "customer": { "name": "João da Silva", "document": "12345678901", "email": "joao@email.com", "phone": "11999999999", "birthdate": "1990-01-01" }, "metadata": { "pedido_id": 1001, "origem": "ecommerce" } } } } }, "responses": { "201": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentTransaction" } } } }, "401": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Endpoint DTVM não configurado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Falha no provedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recomendado para toda operação mutável. Repetir a mesma chave e payload retorna a resposta original e evita processamento financeiro duplicado.", "schema": { "type": "string", "maxLength": 160 } } ] } }, "/api/v1/pix/charges/{id}": { "get": { "tags": [ "PIX" ], "summary": "Consultar cobrança PIX", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentTransaction" } } } }, "404": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/boletos": { "post": { "tags": [ "Boleto" ], "summary": "Emitir boleto", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoletoChargeRequest" }, "example": { "external_id": "pedido-1003", "amount": 299.9, "due_date": "2026-12-10", "payment_limit_date": "2026-12-15", "description": "Pedido 1003", "instructions": "Não receber após a data limite.", "customer": { "name": "Maria Souza", "document": "12345678901", "email": "maria@example.com", "phone": "11999999999", "birthdate": "1990-01-01", "address": { "street": "Avenida Rio Verde", "number": "SN", "neighborhood": "Vila São Tomaz", "city": "Aparecida de Goiânia", "state": "GO", "zip_code": "74915515" } }, "metadata": { "pedido_id": 1003 } } } } }, "responses": { "201": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentTransaction" } } } }, "422": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recomendado para toda operação mutável. Repetir a mesma chave e payload retorna a resposta original e evita processamento financeiro duplicado.", "schema": { "type": "string", "maxLength": 160 } } ] } }, "/api/v1/boletos/{id}": { "get": { "tags": [ "Boleto" ], "summary": "Consultar boleto", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentTransaction" } } } }, "404": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/transactions": { "get": { "tags": [ "Transações" ], "summary": "Listar transações", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "method", "in": "query", "schema": { "type": "string", "enum": [ "PIX", "BOLETO" ] } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "external_id", "in": "query", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "maximum": 100 } } ], "responses": { "200": { "description": "Lista paginada" } } } }, "/api/v1/transactions/{id}": { "get": { "tags": [ "Transações" ], "summary": "Detalhar transação", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentTransaction" } } } }, "404": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/pix/split-rules": { "get": { "tags": [ "Split PIX" ], "summary": "Listar regras de split", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Lista paginada" } } }, "post": { "tags": [ "Split PIX" ], "summary": "Criar regra de split", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixSplitRuleRequest" } } } }, "responses": { "201": { "description": "Regra criada" }, "422": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recomendado para toda operação mutável. Repetir a mesma chave e payload retorna a resposta original e evita processamento financeiro duplicado.", "schema": { "type": "string", "maxLength": 160 } } ] } }, "/api/v1/pix/split-rules/{id}": { "delete": { "tags": [ "Split PIX" ], "summary": "Excluir regra de split", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recomendado para toda operação mutável. Repetir a mesma chave e payload retorna a resposta original e evita processamento financeiro duplicado.", "schema": { "type": "string", "maxLength": 160 } } ], "responses": { "200": { "description": "Regra excluída" }, "404": { "description": "Resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/webhooks/dtvm/pix/{id}": { "post": { "tags": [ "Webhooks" ], "summary": "Webhook DTVM para PIX", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recomendado para toda operação mutável. Repetir a mesma chave e payload retorna a resposta original e evita processamento financeiro duplicado.", "schema": { "type": "string", "maxLength": 160 } } ], "responses": { "200": { "description": "Recebido" } } } }, "/api/v1/webhooks/dtvm/boleto/{id}": { "post": { "tags": [ "Webhooks" ], "summary": "Webhook DTVM para boleto", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recomendado para toda operação mutável. Repetir a mesma chave e payload retorna a resposta original e evita processamento financeiro duplicado.", "schema": { "type": "string", "maxLength": 160 } } ], "responses": { "200": { "description": "Recebido" } } } }, "/api/v1/card/charges": { "post": { "tags": [ "Cartão" ], "summary": "Criar cobrança cartão", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardChargeRequest" } } } }, "responses": { "201": { "description": "Recurso criado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentTransaction" } } } }, "401": { "description": "Token inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Payload inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Falha no provedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recomendado para toda operação mutável. Repetir a mesma chave e payload retorna a resposta original e evita processamento financeiro duplicado.", "schema": { "type": "string", "maxLength": 160 } } ] } }, "/api/v1/card/charges/{id}": { "get": { "tags": [ "Cartão" ], "summary": "Consultar cobrança cartão", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transação encontrada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentTransaction" } } } }, "404": { "description": "Não encontrada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/boletos/{id}/pdf": { "get": { "tags": [ "Boleto" ], "summary": "Baixar PDF do boleto", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "PDF do boleto", "content": { "application/pdf": { "schema": { "type": "string", "contentEncoding": "binary" } } } }, "404": { "description": "Boleto não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "PDF indisponível", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/payment-links": { "get": { "tags": [ "Payment Links" ], "summary": "Listar links de pagamento do cliente autenticado", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "external_id", "in": "query", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Lista paginada de links de pagamento" } } }, "post": { "tags": [ "Payment Links" ], "summary": "Criar link de pagamento hospedado", "description": "Cria uma URL pública /pay/{id} para o pagador escolher PIX, boleto ou cartão. O client_secret nunca deve ser usado no navegador.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkCreateRequest" } } } }, "responses": { "201": { "description": "Link criado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkResponse" } } } }, "422": { "description": "Erro de validação" }, "401": { "description": "Token inválido" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recomendado para toda operação mutável. Repetir a mesma chave e payload retorna a resposta original e evita processamento financeiro duplicado.", "schema": { "type": "string", "maxLength": 160 } } ] } }, "/api/v1/payment-links/{id}": { "get": { "tags": [ "Payment Links" ], "summary": "Consultar link de pagamento e últimas transações", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Dados do link", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkResponse" } } } }, "404": { "description": "Link não encontrado" } }, "description": "Retorna o link e transactions[] com até as 20 transações mais recentes." }, "delete": { "tags": [ "Payment Links" ], "summary": "Cancelar/inativar link de pagamento", "description": "Cancelamento lógico. Impede novos pagamentos e preserva link e transações para auditoria. Operação idempotente.", "operationId": "cancelPaymentLink", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "public_id ou ID do link." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": [ "string", "null" ], "maxLength": 500 } } } } } }, "responses": { "204": { "description": "Link cancelado/inativado com sucesso. Sem corpo." }, "401": { "description": "Token ausente ou inválido." }, "404": { "description": "Link inexistente ou pertencente a outro tenant." }, "422": { "description": "Payload inválido." } } } }, "/api/v1/payers": { "get": { "tags": [ "Pagadores" ], "summary": "Listar pagadores do tenant", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "document", "in": "query", "schema": { "type": "string" } }, { "name": "external_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lista paginada" } } }, "post": { "tags": [ "Pagadores" ], "summary": "Cadastrar pagador", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerUpsertRequest" } } } }, "responses": { "201": { "description": "Pagador criado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payer" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recomendado para toda operação mutável. Repetir a mesma chave e payload retorna a resposta original e evita processamento financeiro duplicado.", "schema": { "type": "string", "maxLength": 160 } } ] } }, "/api/v1/payers/{payer}": { "parameters": [ { "name": "payer", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Pagadores" ], "summary": "Consultar pagador", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Pagador", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payer" } } } } } }, "put": { "tags": [ "Pagadores" ], "summary": "Atualizar pagador", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerUpsertRequest" } } } }, "responses": { "200": { "description": "Pagador atualizado" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recomendado para toda operação mutável. Repetir a mesma chave e payload retorna a resposta original e evita processamento financeiro duplicado.", "schema": { "type": "string", "maxLength": 160 } } ] }, "delete": { "tags": [ "Pagadores" ], "summary": "Excluir ou inativar pagador", "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "Excluído" }, "200": { "description": "Inativado para preservar vínculos" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recomendado para toda operação mutável. Repetir a mesma chave e payload retorna a resposta original e evita processamento financeiro duplicado.", "schema": { "type": "string", "maxLength": 160 } } ] }, "patch": { "tags": [ "Pagadores" ], "summary": "Atualizar parcialmente pagador", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayerUpsertRequest" } } } }, "responses": { "200": { "description": "Pagador atualizado" } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recomendado para toda operação mutável. Repetir a mesma chave e payload retorna a resposta original e evita processamento financeiro duplicado.", "schema": { "type": "string", "maxLength": 160 } } ] } }, "/api/v1/payments/card": { "post": { "tags": [ "Cartão" ], "summary": "Iniciar pagamento de cartão server-to-server com 3DS", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardChargeRequest" } } } }, "responses": { "201": { "description": "Recurso criado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentTransaction" } } } }, "401": { "description": "Token inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Payload inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Falha no provedor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "createCardPayment", "description": "Alias oficial do fluxo de cartão. Cria a transação RenkoPay e chama a autorização 3DS. Se houver challenge, retorna `requires_action=true` e a URL a ser apresentada ao pagador.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recomendado para toda operação mutável. Repetir a mesma chave e payload retorna a resposta original e evita processamento financeiro duplicado.", "schema": { "type": "string", "maxLength": 160 } } ] } }, "/api/v1/payments/card/{id}": { "get": { "tags": [ "Cartão" ], "summary": "Consultar pagamento de cartão server-to-server", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transação encontrada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentTransaction" } } } }, "404": { "description": "Não encontrada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "getCardPayment" } }, "/api/v1/transactions/{id}/cancel": { "post": { "tags": [ "Transações" ], "summary": "Cancelar transação quando o método e estado permitirem", "operationId": "cancelTransaction", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "public_id da transação RenkoPay.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recomendado para toda operação mutável. Repetir a mesma chave e payload retorna a resposta original e evita processamento financeiro duplicado.", "schema": { "type": "string", "maxLength": 160 } } ], "responses": { "200": { "description": "Operação processada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentResponse" } } } }, "401": { "description": "Token ausente, inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou pertencente a outro tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Operação não suportada ou parâmetros inválidos. Recusa definitiva.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessRuleError" } } } }, "502": { "description": "Falha de comunicação ou processamento na adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Estado incompatível da transação. Recusa definitiva.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessRuleError" }, "example": { "message": "Reembolso/estorno é permitido apenas para transações pagas ou autorizadas/pendentes.", "code": "TRANSACTION_STATE_CONFLICT" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelRequest" } } } }, "description": "409 e 422 são recusas definitivas de negócio e não devem receber retry automático." } }, "/api/v1/transactions/{id}/refund": { "post": { "tags": [ "Transações" ], "summary": "Estornar/devolver transação", "operationId": "refundTransaction", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "public_id da transação RenkoPay.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recomendado para toda operação mutável. Repetir a mesma chave e payload retorna a resposta original e evita processamento financeiro duplicado.", "schema": { "type": "string", "maxLength": 160 } } ], "responses": { "200": { "description": "Operação processada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustmentResponse" } } } }, "401": { "description": "Token ausente, inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou pertencente a outro tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Regra de negócio, parcial não suportado ou recusa do provedor. Nenhum retry automático infinito.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/BusinessRuleError" }, { "$ref": "#/components/schemas/PixPartialRefundUnsupportedError" }, { "$ref": "#/components/schemas/ProviderRefundRejectedAdjustment" } ] }, "examples": { "pix_partial_unsupported": { "summary": "PIX parcial não suportado", "value": { "message": "Estorno parcial de PIX não é suportado pela integração atual. Para devolver o PIX, utilize scope TOTAL sem amount.", "code": "PIX_PARTIAL_REFUND_UNSUPPORTED" } }, "provider_temporarily_unavailable": { "summary": "Provedor recusou devolução total", "value": { "data": { "action": "REFUND", "scope": "TOTAL", "status": "FAILED", "http_status": 404, "error_message": "Estorno temporariamente indisponível para esta cobrança.", "response_payload": { "code": "404", "message": "Estorno temporariamente indisponível para esta cobrança." } } } } } } } }, "502": { "description": "Falha técnica de transporte/comunicação com o provedor, sem resposta de negócio utilizável.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Estado incompatível da transação. Recusa definitiva.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessRuleError" }, "example": { "message": "Reembolso/estorno é permitido apenas para transações pagas ou autorizadas/pendentes.", "code": "TRANSACTION_STATE_CONFLICT" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundRequest" }, "examples": { "pix_total": { "summary": "PIX: devolução total", "value": { "scope": "TOTAL", "notes": "Solicitação de devolução integral" } }, "partial_when_supported": { "summary": "Parcial quando o método/provedor suportar", "value": { "scope": "PARTIAL", "amount": 25.5, "reason": "OTHERS", "notes": "Estorno parcial" } } } } } }, "description": "Solicita estorno/reembolso. O `{id}` é sempre o public_id UUID RenkoPay. Para PIX na integração atual, use `{\"scope\":\"TOTAL\"}` sem `amount`. Estorno parcial de PIX retorna HTTP 422 e não chama o provedor. Quando o provedor recebe a solicitação total mas a recusa, a RenkoPay retorna HTTP 422 com ajuste `FAILED`; nenhuma movimentação financeira local deve ser considerada concluída. 409 e 422 são recusas definitivas para aquela tentativa e não devem receber retry automático infinito." } }, "/api/v1/transactions/{id}/capture": { "post": { "tags": [ "Transações" ], "summary": "Capturar cartão previamente autorizado", "operationId": "captureTransaction", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "public_id da transação RenkoPay.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recomendado para toda operação mutável. Repetir a mesma chave e payload retorna a resposta original e evita processamento financeiro duplicado.", "schema": { "type": "string", "maxLength": 160 } } ], "responses": { "200": { "description": "Operação processada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderOperationResponse" } } } }, "401": { "description": "Token ausente, inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou pertencente a outro tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erro de validação ou operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "502": { "description": "Falha de comunicação ou processamento na adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/transactions/{id}/sync-provider": { "post": { "tags": [ "Transações" ], "summary": "Sincronizar e reconciliar o status da transação", "operationId": "syncTransactionProvider", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "public_id UUID da transação RenkoPay. Ex.: 6bd28724-d718-412f-989a-8a8746b24329.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recomendado para toda operação mutável. Repetir a mesma chave e payload retorna a resposta original e evita processamento financeiro duplicado.", "schema": { "type": "string", "maxLength": 160 } } ], "responses": { "200": { "description": "Transação reconciliada com sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionSyncResponse" }, "example": { "data": { "id": "6bd28724-d718-412f-989a-8a8746b24329", "external_id": "pedido-1001", "previous_status": "UNKNOWN", "status": "PAID", "provider_status": "PAID", "reconciled": true, "synchronized_at": "2026-08-27T16:30:00Z" } } } } }, "401": { "description": "Token ausente, inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou pertencente a outro tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Sincronização não suportada para o provedor/método atual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessRuleError" } } } }, "502": { "description": "Falha técnica/transitória ao consultar o provedor. Retry permitido com backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Referência interna do provedor não pôde ser resolvida com segurança. Não repetir indefinidamente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderReferenceUnresolvedError" }, "example": { "message": "Não foi possível resolver a referência interna da cobrança para sincronização.", "code": "PROVIDER_REFERENCE_UNRESOLVED" } } } } }, "description": "Força uma consulta ao provedor para reconciliar o status atual. O `{id}` deve ser sempre o public_id UUID da RenkoPay. Nunca envie provider_transaction_id, charge_id ou identificadores internos da adquirente. Use quando o status estiver UNKNOWN ou quando for necessário confirmar novamente o estado real da transação. HTTP 409 é recusa definitiva para aquela tentativa; HTTP 502 indica falha técnica/transitória e pode receber retry com backoff." } }, "/api/v1/acquirer/charges": { "get": { "tags": [ "Adquirente, Cobranças" ], "summary": "Listar cobranças Adquirente do contexto do tenant", "operationId": "listAcquirerCharges", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Resposta normalizada da Adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquirerProxyResponse" } } } }, "401": { "description": "Token ausente, inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou pertencente a outro tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erro de validação ou operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "502": { "description": "Falha de comunicação ou processamento na adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/acquirer/charges/{id}": { "get": { "tags": [ "Adquirente, Cobranças" ], "summary": "Consultar cobrança Adquirente", "operationId": "getAcquirerCharge", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID da charge Adquirente.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resposta normalizada da Adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquirerProxyResponse" } } } }, "401": { "description": "Token ausente, inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou pertencente a outro tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erro de validação ou operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "502": { "description": "Falha de comunicação ou processamento na adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/acquirer/charges/{chargeId}/splits": { "get": { "tags": [ "Adquirente, Cobranças" ], "summary": "Listar splits de uma cobrança", "operationId": "listAcquirerChargeSplits", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "chargeId", "in": "path", "required": true, "description": "ID da charge Adquirente.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resposta normalizada da Adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquirerProxyResponse" } } } }, "401": { "description": "Token ausente, inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou pertencente a outro tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erro de validação ou operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "502": { "description": "Falha de comunicação ou processamento na adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Adquirente, Cobranças" ], "summary": "Criar split pós-venda", "operationId": "createAcquirerChargeSplit", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "chargeId", "in": "path", "required": true, "description": "ID da charge Adquirente.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recomendado para toda operação mutável. Repetir a mesma chave e payload retorna a resposta original e evita processamento financeiro duplicado.", "schema": { "type": "string", "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquirerSplitRequest" } } } }, "responses": { "201": { "description": "Recurso criado na Adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquirerProxyResponse" } } } }, "401": { "description": "Token ausente, inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou pertencente a outro tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erro de validação ou operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "502": { "description": "Falha de comunicação ou processamento na adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Adquirente, Cobranças" ], "summary": "Cancelar split pós-venda", "operationId": "cancelAcquirerChargeSplit", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "chargeId", "in": "path", "required": true, "description": "ID da charge Adquirente.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recomendado para toda operação mutável. Repetir a mesma chave e payload retorna a resposta original e evita processamento financeiro duplicado.", "schema": { "type": "string", "maxLength": 160 } } ], "responses": { "200": { "description": "Resposta normalizada da Adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquirerProxyResponse" } } } }, "401": { "description": "Token ausente, inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou pertencente a outro tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erro de validação ou operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "502": { "description": "Falha de comunicação ou processamento na adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/acquirer/invoices": { "get": { "tags": [ "Adquirente, Faturas" ], "summary": "Listar faturas", "operationId": "listAcquirerInvoices", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Resposta normalizada da Adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquirerProxyResponse" } } } }, "401": { "description": "Token ausente, inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou pertencente a outro tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erro de validação ou operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "502": { "description": "Falha de comunicação ou processamento na adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Adquirente, Faturas" ], "summary": "Criar fatura", "operationId": "createAcquirerInvoice", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreeFormProviderPayload" } } } }, "responses": { "201": { "description": "Recurso criado na Adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquirerProxyResponse" } } } }, "401": { "description": "Token ausente, inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou pertencente a outro tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erro de validação ou operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "502": { "description": "Falha de comunicação ou processamento na adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recomendado para toda operação mutável. Repetir a mesma chave e payload retorna a resposta original e evita processamento financeiro duplicado.", "schema": { "type": "string", "maxLength": 160 } } ] } }, "/api/v1/acquirer/invoices/{id}": { "get": { "tags": [ "Adquirente, Faturas" ], "summary": "Consultar fatura", "operationId": "getAcquirerInvoice", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID da fatura Adquirente.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resposta normalizada da Adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquirerProxyResponse" } } } }, "401": { "description": "Token ausente, inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou pertencente a outro tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erro de validação ou operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "502": { "description": "Falha de comunicação ou processamento na adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/acquirer/invoices/{id}/send-email": { "post": { "tags": [ "Adquirente, Faturas" ], "summary": "Enviar fatura por e-mail", "operationId": "sendAcquirerInvoiceEmail", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID da fatura Adquirente.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recomendado para toda operação mutável. Repetir a mesma chave e payload retorna a resposta original e evita processamento financeiro duplicado.", "schema": { "type": "string", "maxLength": 160 } } ], "responses": { "200": { "description": "Resposta normalizada da Adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquirerProxyResponse" } } } }, "401": { "description": "Token ausente, inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou pertencente a outro tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erro de validação ou operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "502": { "description": "Falha de comunicação ou processamento na adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/acquirer/recurring-invoices": { "post": { "tags": [ "Adquirente, Faturas" ], "summary": "Criar fatura recorrente", "operationId": "createAcquirerRecurringInvoice", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreeFormProviderPayload" } } } }, "responses": { "201": { "description": "Recurso criado na Adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquirerProxyResponse" } } } }, "401": { "description": "Token ausente, inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou pertencente a outro tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erro de validação ou operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "502": { "description": "Falha de comunicação ou processamento na adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recomendado para toda operação mutável. Repetir a mesma chave e payload retorna a resposta original e evita processamento financeiro duplicado.", "schema": { "type": "string", "maxLength": 160 } } ] } }, "/api/v1/acquirer/subscriptions": { "get": { "tags": [ "Adquirente, Assinaturas" ], "summary": "Listar assinaturas", "operationId": "listAcquirerSubscriptions", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Resposta normalizada da Adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquirerProxyResponse" } } } }, "401": { "description": "Token ausente, inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou pertencente a outro tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erro de validação ou operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "502": { "description": "Falha de comunicação ou processamento na adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/acquirer/subscriptions/plans/{planId}": { "post": { "tags": [ "Adquirente, Assinaturas" ], "summary": "Criar assinatura de cartão para um plano", "operationId": "createAcquirerSubscription", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "planId", "in": "path", "required": true, "description": "ID do plano Adquirente.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recomendado para toda operação mutável. Repetir a mesma chave e payload retorna a resposta original e evita processamento financeiro duplicado.", "schema": { "type": "string", "maxLength": 160 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreeFormProviderPayload" } } } }, "responses": { "201": { "description": "Recurso criado na Adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquirerProxyResponse" } } } }, "401": { "description": "Token ausente, inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou pertencente a outro tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erro de validação ou operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "502": { "description": "Falha de comunicação ou processamento na adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/acquirer/subscriptions/{id}": { "get": { "tags": [ "Adquirente, Assinaturas" ], "summary": "Consultar assinatura", "operationId": "getAcquirerSubscription", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID da assinatura Adquirente.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resposta normalizada da Adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquirerProxyResponse" } } } }, "401": { "description": "Token ausente, inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou pertencente a outro tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erro de validação ou operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "502": { "description": "Falha de comunicação ou processamento na adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Adquirente, Assinaturas" ], "summary": "Cancelar assinatura", "operationId": "cancelAcquirerSubscription", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID da assinatura Adquirente.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Recomendado para toda operação mutável. Repetir a mesma chave e payload retorna a resposta original e evita processamento financeiro duplicado.", "schema": { "type": "string", "maxLength": 160 } } ], "responses": { "200": { "description": "Resposta normalizada da Adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquirerProxyResponse" } } } }, "401": { "description": "Token ausente, inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou pertencente a outro tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erro de validação ou operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "502": { "description": "Falha de comunicação ou processamento na adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/acquirer/account/balance": { "get": { "tags": [ "Adquirente, Conta e Recebíveis" ], "summary": "Consultar saldo do seller", "operationId": "getAcquirerSellerBalance", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Resposta normalizada da Adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquirerProxyResponse" } } } }, "401": { "description": "Token ausente, inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou pertencente a outro tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erro de validação ou operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "502": { "description": "Falha de comunicação ou processamento na adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/acquirer/account/transfers": { "get": { "tags": [ "Adquirente, Conta e Recebíveis" ], "summary": "Listar transferências do seller", "operationId": "listAcquirerSellerTransfers", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Resposta normalizada da Adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquirerProxyResponse" } } } }, "401": { "description": "Token ausente, inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou pertencente a outro tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erro de validação ou operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "502": { "description": "Falha de comunicação ou processamento na adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/acquirer/account/transfers/{id}": { "get": { "tags": [ "Adquirente, Conta e Recebíveis" ], "summary": "Consultar transferência do seller", "operationId": "getAcquirerSellerTransfer", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID da transferência Adquirente.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resposta normalizada da Adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquirerProxyResponse" } } } }, "401": { "description": "Token ausente, inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou pertencente a outro tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erro de validação ou operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "502": { "description": "Falha de comunicação ou processamento na adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/acquirer/account/adjustments": { "get": { "tags": [ "Adquirente, Conta e Recebíveis" ], "summary": "Listar ajustes financeiros", "operationId": "listAcquirerSellerAdjustments", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Resposta normalizada da Adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquirerProxyResponse" } } } }, "401": { "description": "Token ausente, inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou pertencente a outro tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erro de validação ou operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "502": { "description": "Falha de comunicação ou processamento na adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/acquirer/account/future-transfers": { "get": { "tags": [ "Adquirente, Conta e Recebíveis" ], "summary": "Listar recebíveis/transferências futuras", "operationId": "listAcquirerFutureTransfers", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Resposta normalizada da Adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquirerProxyResponse" } } } }, "401": { "description": "Token ausente, inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou pertencente a outro tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erro de validação ou operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "502": { "description": "Falha de comunicação ou processamento na adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/acquirer/account/receivables/totals": { "get": { "tags": [ "Adquirente, Conta e Recebíveis" ], "summary": "Consultar total de recebíveis", "operationId": "getAcquirerReceivableTotals", "security": [ { "bearerAuth": [] } ], "parameters": [], "responses": { "200": { "description": "Resposta normalizada da Adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquirerProxyResponse" } } } }, "401": { "description": "Token ausente, inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou pertencente a outro tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erro de validação ou operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "502": { "description": "Falha de comunicação ou processamento na adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/acquirer/account/transactions/{uuid}/installments": { "get": { "tags": [ "Adquirente, Conta e Recebíveis" ], "summary": "Consultar parcelas de uma transação", "operationId": "getAcquirerTransactionInstallments", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "UUID da transação Adquirente.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resposta normalizada da Adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcquirerProxyResponse" } } } }, "401": { "description": "Token ausente, inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Recurso inexistente ou pertencente a outro tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Erro de validação ou operação não permitida", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "502": { "description": "Falha de comunicação ou processamento na adquirente", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/health/performance": { "get": { "tags": [ "High Performance" ], "summary": "Health check da camada High Performance", "operationId": "performanceHealth", "security": [], "responses": { "200": { "description": "Banco, cache e Redis saudáveis quando habilitado" }, "503": { "description": "Infraestrutura degradada" } } } }, "/pay/{paymentLink}": { "get": { "tags": [ "Hosted Checkout" ], "summary": "Abrir Hosted Checkout do link de pagamento", "description": "Renderiza o checkout com branding do tenant proprietário do link. Caso o tenant não possua personalização, utiliza o tema padrão do RenkoPay Gateway.", "security": [], "parameters": [ { "name": "paymentLink", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Página HTML do checkout", "content": { "text/html": { "schema": { "type": "string" } } } }, "410": { "description": "Link expirado, cancelado ou indisponível" } } }, "post": { "tags": [ "Hosted Checkout" ], "summary": "Processar pagamento no Hosted Checkout", "description": "Processa PIX, boleto, crédito ou débito conforme os métodos habilitados no link. Cartões utilizam 3DS quando exigido.", "security": [], "parameters": [ { "name": "paymentLink", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "302": { "description": "Redirecionamento para resultado ou challenge 3DS" }, "422": { "description": "Erro de validação com nomes amigáveis em português" } } } }, "/api/v1/receivers": { "get": { "tags": [ "Recebedores / Marketplace" ], "summary": "Listar recebedores do tenant", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Lista de recebedores" } } }, "post": { "tags": [ "Recebedores / Marketplace" ], "summary": "Criar recebedor e opcionalmente cadastrá-lo na Adquirente (RenkoPay)", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiverUpsertRequest" } } } }, "responses": { "201": { "description": "Recebedor criado" } } } }, "/api/v1/receivers/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "tags": [ "Recebedores / Marketplace" ], "summary": "Consultar recebedor", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Recebedor" } } }, "patch": { "tags": [ "Recebedores / Marketplace" ], "summary": "Atualizar recebedor", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiverUpsertRequest" } } } }, "responses": { "200": { "description": "Atualizado" } } }, "delete": { "tags": [ "Recebedores / Marketplace" ], "summary": "Inativar recebedor", "security": [ { "BearerAuth": [] } ], "responses": { "204": { "description": "Inativado" } } }, "put": { "tags": [ "Recebedores / Marketplace" ], "summary": "Atualizar recebedor", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiverUpsertRequest" } } } }, "responses": { "200": { "description": "Atualizado" } } } }, "/api/v1/receivers/{id}/sync": { "post": { "tags": [ "Recebedores / Marketplace" ], "summary": "Sincronizar cadastro/KYC com a Adquirente (RenkoPay)", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sincronizado" } } } }, "/api/v1/receivers/split-settings": { "get": { "tags": [ "Recebedores / Marketplace" ], "summary": "Consultar regra de comissão do tenant", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Configuração" } } }, "put": { "tags": [ "Recebedores / Marketplace" ], "summary": "Configurar percentual de comissão e recebedor de destino", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiverSplitSettings" } } } }, "responses": { "200": { "description": "Configuração atualizada" } } } }, "/api/v1/acquirers/capabilities": { "get": { "tags": [ "Adquirência" ], "summary": "Consultar capacidades das adquirentes configuradas", "operationId": "getAcquirerCapabilities", "security": [], "responses": { "200": { "description": "Capacidades disponíveis." } } } } }, "externalDocs": { "description": "Portal RenkoPay para desenvolvedores", "url": "https://gateway.renkopay.com.br/desenvolvedores" }, "x-generated-at": "2026-08-27T12:11:00-03:00", "x-source": "gateway.renkopay.com.br.tar.gz fornecido em 2026-08-27", "webhooks": { "paymentPaid": { "post": { "tags": [ "Webhooks enviados ao cliente" ], "summary": "Pagamento confirmado", "description": "Exemplo de evento outbound. O endpoint do cliente deve responder 2xx; 200 ou 204 são recomendados.", "parameters": [ { "name": "X-Gateway-Event", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Gateway-Delivery", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Gateway-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Gateway-Tenant", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Gateway-Transaction", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientWebhookPayload" }, "example": { "event": "payment.pix.paid", "id": "94c620a3-c0e7-4d59-b09f-cdbdeabae694", "created_at": "2026-08-27T15:30:00Z", "data": { "transaction_id": "d180e943-0ef0-4cef-8ae1-fcf914fb3732", "tenant_id": "tenant-uuid", "external_id": "pedido-1001", "method": "PIX", "status": "PAID", "amount": 100.0, "currency": "BRL", "provider": "DELTAPAG", "provider_status": "PAID", "paid_at": "2026-08-27T15:29:58Z", "failed_at": null } } } } }, "responses": { "200": { "description": "Webhook recebido pelo cliente." }, "204": { "description": "Webhook recebido sem conteúdo de resposta." } } } }, "paymentFailed": { "post": { "tags": [ "Webhooks enviados ao cliente" ], "summary": "Pagamento falhou/foi recusado", "description": "Exemplo de evento negativo outbound. Respostas não-2xx do endpoint do cliente são tratadas como falha de entrega e podem gerar retry.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientWebhookPayload" }, "example": { "event": "payment.pix.failed", "id": "e64b84c9-605e-43f5-a90d-409360295d34", "created_at": "2026-08-27T15:31:00Z", "data": { "transaction_id": "8b1d2e05-4df5-4f8b-bb6a-d47b5d5de284", "tenant_id": "tenant-uuid", "external_id": "pedido-1002", "method": "PIX", "status": "FAILED", "amount": 100.0, "currency": "BRL", "provider": "DELTAPAG", "provider_status": "FAILED", "paid_at": null, "failed_at": "2026-08-27T15:30:59Z" } } } } }, "responses": { "200": { "description": "Webhook recebido pelo cliente." }, "204": { "description": "Webhook recebido sem conteúdo de resposta." } } } } } }