{ "openapi": "3.1.0", "info": { "title": "ZWAY API de pagamentos", "version": "1.0.0", "description": "API única: todas as moedas e métodos em POST /payments. Valores em centavos da moeda." }, "servers": [ { "url": "https://api.zwaybr.com/api/v1" } ], "security": [ { "bearer": [] } ], "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer" } }, "schemas": { "Erro": { "type": "object", "properties": { "error": { "type": "boolean" }, "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "timestamp": { "type": "string" } } } } }, "paths": { "/payments": { "post": { "summary": "Criar pagamento", "description": "Uma rota para todas as moedas e métodos: currency e paymentMethod decidem o fluxo. Os campos exigidos mudam conforme o método.", "operationId": "criarPagamento", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 120 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "currency", "paymentMethod", "amount", "name", "email" ], "properties": { "currency": { "type": "string" }, "paymentMethod": { "type": "string" }, "amount": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "document": { "type": "object" }, "phone": { "type": "string" }, "items": { "type": "array" }, "externalId": { "type": "string" }, "postbackUrl": { "type": "string" }, "returnUrl": { "type": "string" }, "cancelUrl": { "type": "string" }, "country": { "type": "string" }, "birthDate": { "type": "string" }, "birthCountry": { "type": "string" }, "cardToken": { "type": "string" }, "tokenOrigin": { "type": "string" }, "installments": { "type": "integer" }, "cep": { "type": "string" }, "street": { "type": "string" }, "number": { "type": "string" }, "district": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "expiresAt": { "type": "string" } } }, "examples": { "PIX_BRL": { "value": { "currency": "BRL", "paymentMethod": "PIX", "amount": 9990, "name": "Maria Souza", "email": "maria@exemplo.com.br", "document": { "type": "cpf", "number": "12345678909" }, "phone": "11999999999", "items": [ { "title": "Plano Pro", "unitPrice": 9990, "quantity": 1 } ] } }, "BOLETO_BRL": { "value": { "currency": "BRL", "paymentMethod": "BOLETO", "amount": 9990, "name": "Maria Souza", "email": "maria@exemplo.com.br", "document": { "type": "cpf", "number": "12345678909" }, "items": [ { "title": "Plano Pro", "unitPrice": 9990, "quantity": 1 } ] } }, "CREDIT_CARD_BRL": { "value": { "currency": "BRL", "paymentMethod": "CREDIT_CARD", "amount": 9990, "name": "Maria Souza", "email": "maria@exemplo.com.br", "document": { "type": "cpf", "number": "12345678909" }, "items": [ { "title": "Plano Pro", "unitPrice": 9990, "quantity": 1 } ], "cardToken": "TOKEN_GERADO_NO_NAVEGADOR", "tokenOrigin": "provedor" } }, "SPEI_MXN": { "value": { "currency": "MXN", "paymentMethod": "SPEI", "amount": 50000, "name": "Juan Pérez López", "email": "juan@ejemplo.mx", "document": { "type": "rfc", "number": "PELJ900131AB1" }, "birthDate": "1990-01-31", "birthCountry": "MX", "returnUrl": "https://sualoja.com/obrigado" } }, "OXXO_MXN": { "value": { "currency": "MXN", "paymentMethod": "OXXO", "amount": 50000, "name": "Juan Pérez López", "email": "juan@ejemplo.mx", "returnUrl": "https://sualoja.com/obrigado" } } } } } }, "responses": { "200": { "description": "Pagamento criado", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "zw_1760000000000_ab12cd34", "externalId": "pedido-0001", "status": "PENDING", "method": "PIX", "currency": "BRL", "amount": 9990, "pix": { "qrCode": "00020101021226…6304ABCD" }, "timestamps": { "expiresAt": "2026-10-13T15:00:00.000Z", "createdAt": "2026-10-12T15:00:00.000Z", "updatedAt": "2026-10-12T15:00:00.000Z" } } } } }, "400": { "description": "Dados inválidos", "content": { "application/json": { "schema": { "type": "object" }, "example": { "error": true, "code": "VALIDATION_ERROR", "message": "Dados inválidos", "details": [ { "field": "email", "message": "Invalid email" } ], "timestamp": "2026-10-12T15:00:00.000Z" } } } }, "401": { "description": "Sem autenticação", "content": { "application/json": { "schema": { "type": "object" }, "example": { "error": "Unauthorized", "code": "AUTH_FAILED", "message": "Chave de API inválida" } } } }, "422": { "description": "Não processável", "content": { "application/json": { "schema": { "type": "object" }, "example": { "error": true, "code": "IDEMPOTENCY_KEY_REUSED", "message": "Idempotency-Key (ou externalId) já usada com outro pedido", "timestamp": "2026-10-12T15:00:00.000Z" } } } } } } }, "/payments/{id}": { "get": { "summary": "Buscar pagamento", "description": "Consulta qualquer pagamento, em qualquer moeda. Pagamento de outra conta devolve o mesmo 404 de um id inexistente.", "operationId": "buscarPagamento", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Pagamento", "content": { "application/json": { "schema": { "type": "object" }, "example": { "id": "zw_1760000000000_ab12cd34", "externalId": "pedido-0001", "status": "APPROVED", "method": "PIX", "currency": "BRL", "amount": 9990, "fee": 200, "netAmount": 9790, "pix": { "qrCode": null }, "timestamps": { "expiresAt": "2026-10-13T15:00:00.000Z", "createdAt": "2026-10-12T15:00:00.000Z", "updatedAt": "2026-10-12T15:00:00.000Z", "paidAt": "2026-10-12T15:02:10.000Z" } } } } }, "404": { "description": "Não encontrado", "content": { "application/json": { "schema": { "type": "object" }, "example": { "error": true, "code": "NOT_FOUND", "message": "Pagamento não encontrado", "timestamp": "2026-10-12T15:00:00.000Z" } } } } } } }, "/payments/methods": { "get": { "summary": "Moedas e métodos", "description": "Lista as moedas e os métodos liberados para a sua conta, com valor mínimo/máximo e os campos exigidos de cada método.", "operationId": "listarMetodos", "parameters": [ { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Moedas e métodos", "content": { "application/json": { "schema": { "type": "object" }, "example": { "currencies": [ { "currency": "BRL", "name": "Real brasileiro", "symbol": "R$", "decimals": 2, "country": "BR", "methods": [ { "paymentMethod": "PIX", "name": "PIX", "minAmount": 500, "maxAmount": null, "requiredFields": [ "name", "email", "document", "phone", "items" ], "optionalFields": [ "externalId", "postbackUrl" ] }, { "paymentMethod": "BOLETO", "name": "Boleto", "minAmount": 100, "maxAmount": null, "requiredFields": [ "name", "email", "document", "items" ], "optionalFields": [ "externalId", "postbackUrl" ] }, { "paymentMethod": "CREDIT_CARD", "name": "Cartão de crédito", "minAmount": 100, "maxAmount": null, "requiredFields": [ "name", "email", "document", "items", "cardToken", "tokenOrigin" ], "optionalFields": [ "externalId", "postbackUrl" ] } ] }, { "currency": "MXN", "name": "Peso mexicano", "symbol": "MX$", "decimals": 2, "country": "MX", "methods": [ { "paymentMethod": "SPEI", "name": "SPEI", "minAmount": 1, "maxAmount": 2000000000, "requiredFields": [ "name", "document.type", "document.number", "birthDate", "birthCountry" ], "optionalFields": [ "externalId" ] }, { "paymentMethod": "OXXO", "name": "OXXO", "minAmount": 1000, "maxAmount": 1000000, "requiredFields": [], "optionalFields": [ "externalId" ] } ] } ] } } } } } } }, "/payments/card-configuration": { "get": { "summary": "Configuração do cartão", "description": "Script e chave pública para tokenizar o cartão no navegador do comprador. O número do cartão nunca passa pelo seu servidor: envie só o cardToken.", "operationId": "configuracaoCartao", "responses": { "200": { "description": "Configuração do cartão", "content": { "application/json": { "schema": { "type": "object" }, "example": { "tokenization": "provedor", "publicKey": "PUBLIC_KEY", "scriptUrl": "https://…", "tokenizadores": [ { "ref": 1, "tokenization": "provedor", "publicKey": "PUBLIC_KEY" } ] } } } } } } } } }