{
"openapi": "3.1.0",
"info": {
"title": "EMV Gateway API",
"version": "1.0.0",
"description": "API do EMV Gateway: pagamentos com cartão de crédito, Pix e boleto, com divisão automática dos valores (split) entre recebedores.\n\n# Como começar\n\n1. **Acesse o painel** com o usuário enviado pela EMV e gere a sua chave de API em **Configurações**.\n2. **Use o endereço do ambiente:**\n - Sandbox (testes, sem dinheiro real): `https://sandbox-pay.emvtech.com.br`\n - Produção: informado pela EMV quando a sua conta de produção for liberada.\n3. **Crie um recebedor** (`POST /Recipients`): é quem recebe o dinheiro das vendas. Sem recebedor, os pedidos são recusados.\n4. **Crie o primeiro pedido** (`POST /Orders`) com Pix ou cartão. Veja **Como pagar com cartão** abaixo.\n5. **Cadastre um webhook** para ser avisado quando o pagamento for confirmado. Veja **Webhooks** abaixo.\n\nEsta documentação traz o que o seu sistema faz pela API. Dados da empresa, taxas, troca da chave de API, relatórios, extratos, recebíveis e listagens ficam no painel.\n\nEm cada requisição, o botão **Testar Requisição** chama o sandbox direto desta página: informe a sua chave `gw_test_...` em **Autenticação**.\n\n## Autenticação\n\nTodas as requisições levam a chave de API no header:\n\n```\nAuthorization: Bearer gw_test_xxxxxxxxxxxxxxxx\n```\n\n- `gw_test_...` funciona só no sandbox; `gw_live_...`, só em produção.\n- A chave dá acesso total à sua conta: use apenas no seu servidor, **nunca** no navegador ou no app.\n- Se a chave vazar, gere outra no painel (**Configurações**): a anterior para de funcionar na hora.\n\n## Idempotency-Key\n\nHeader **opcional e recomendado** em `POST`, `PUT` e `DELETE`: um identificador único por operação (ex.: um UUID ou o id do pedido no seu sistema).\n\nSe a mesma requisição for reenviada com a mesma chave em até 24 h (ex.: depois de uma falha de rede), a API devolve a mesma resposta, **sem criar ou cobrar de novo**.\n\n```\nIdempotency-Key: pedido-123\n```\n\n## Valores e formatos\n\n- Valores sempre **em centavos**: `10000` = R$ 100,00.\n- Datas em ISO 8601 (UTC): `2026-11-05T04:32:04.983Z`.\n- Corpo das requisições em JSON (`Content-Type: application/json`).\n- Toda resposta de sucesso vem dentro de `data`; todo erro, dentro de `error` (veja **Referência**).\n\n## Sandbox\n\nNenhum valor é cobrado de verdade.\n\n- Cartão aprovado: `4000 0000 0000 0010`, qualquer nome, validade futura, CVV `123`.\n- Cartão recusado: CVV começando com `6` (ex.: `612`).\n- Pix é pago automaticamente alguns instantes após a criação.\n- Boleto está temporariamente indisponível no sandbox (veja **Limitações do sandbox** em **Referência**).\n\n# Como pagar com cartão\n\nPor segurança, **a API não recebe número nem CVV do cartão**. O cartão é transformado em um **token** direto no navegador do comprador, pelo nosso script `emv.js`, e só o token chega ao seu servidor. Assim, os dados do cartão nunca passam pelo seu sistema.\n\n**O fluxo tem 3 passos:**\n\n1. **Seu backend** busca a chave pública: `GET /Cards/publicKey`.\n2. **Seu checkout** (navegador) carrega o `emv.js` e tokeniza o cartão. Ele recebe um `token_...`.\n3. **Seu backend** cria o pedido com o token: `POST /Orders` com `card_token`.\n\n> O token é de **uso único** e **expira em cerca de 1 minuto**. Tokenize no momento do pagamento, nunca antes.\n\n## Passo 1: buscar a chave pública (backend)\n\nNos exemplos com `curl`, `$EMV_API_KEY` é a sua chave de API (`gw_test_...` no sandbox). Para testar no terminal: `export EMV_API_KEY=gw_test_...`.\n\n```bash\ncurl https://sandbox-pay.emvtech.com.br/Cards/publicKey \\\n -H \"Authorization: Bearer $EMV_API_KEY\"\n```\n\n```json\n{ \"data\": { \"object\": \"public_key\", \"public_key\": \"pk_test_xxxxxxxx\", \"livemode\": false } }\n```\n\nA `public_key` **não é segredo** e pode ir para o navegador. Você pode guardá-la em cache. Já a sua chave de API (`gw_test_...` / `gw_live_...`) **nunca** pode ir para o navegador.\n\n## Passo 2: tokenizar o cartão (checkout)\n\nCarregue o script na página de pagamento:\n\n```html\n\n```\n\n### HTML / JavaScript\n\n```html\n\n\n\n\n```\n\n### React\n\nCrie um helper que carrega o script uma vez:\n\n```js\n// src/lib/emv.js\nlet carregando;\n\nexport function loadEMV() {\n if (window.EMV) return Promise.resolve(window.EMV);\n if (!carregando) {\n carregando = new Promise((resolve, reject) => {\n const script = document.createElement(\"script\");\n script.src = \"https://js.emvtech.com.br/v1/emv.js\";\n script.onload = () => resolve(window.EMV);\n script.onerror = () => { carregando = null; reject(new Error(\"Falha ao carregar emv.js\")); };\n document.head.appendChild(script);\n });\n }\n return carregando;\n}\n```\n\nComponente de cartão:\n\n```jsx\nimport { useEffect, useState } from \"react\";\nimport { loadEMV } from \"./lib/emv\";\n\nexport function CardForm({ publicKey, onToken }) {\n const [emv, setEmv] = useState(null);\n const [card, setCard] = useState({ number: \"\", holder_name: \"\", exp_month: \"\", exp_year: \"\", cvv: \"\" });\n const [erro, setErro] = useState(null);\n const [enviando, setEnviando] = useState(false);\n\n useEffect(() => {\n loadEMV().then(EMV => setEmv(EMV(publicKey))).catch(e => setErro(e.message));\n }, [publicKey]);\n\n const campo = nome => e => {\n const valor = nome === \"number\" ? window.EMV.formatCardNumber(e.target.value) : e.target.value;\n setCard(c => ({ ...c, [nome]: valor }));\n };\n\n async function pagar(e) {\n e.preventDefault();\n setErro(null);\n setEnviando(true);\n try {\n const { token } = await emv.tokenize(card);\n await onToken(token); // envie o token para o seu backend\n } catch (err) {\n setErro(err.message);\n } finally {\n setEnviando(false);\n }\n }\n\n return (\n \n );\n}\n```\n\nUso:\n\n```jsx\n fetch(\"/api/checkout\", {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: JSON.stringify({ card_token: token }),\n })}\n/>\n```\n\n### Next.js\n\nUse o mesmo componente acima com `\"use client\"` no topo do arquivo. Para carregar o script, você pode usar o `loadEMV` ou o componente `Script` do Next:\n\n```jsx\nimport Script from \"next/script\";\n\n\n```\n\n### TypeScript\n\nOs tipos estão em `https://js.emvtech.com.br/v1/emv.d.ts`. Copie o arquivo para o seu projeto (ex.: `src/types/emv.d.ts`) para ter autocomplete de `window.EMV`, dos campos e dos códigos de erro.\n\n### Validar antes de enviar (opcional)\n\n`emv.tokenize` já valida o cartão antes de chamar a rede. Para mostrar erros campo a campo enquanto o comprador digita, use:\n\n```js\nconst { valid, brand, errors } = emv.validate(card);\n// errors: [{ field: \"cvv\", code: \"invalid_cvv\", message: \"Código de segurança (CVV) inválido.\" }]\n\nEMV.cardBrand(\"5207 4209 9953 6931\"); // \"mastercard\" (para mostrar o ícone da bandeira)\n```\n\n## Passo 3: criar o pedido com o token (backend)\n\n```bash\ncurl https://sandbox-pay.emvtech.com.br/Orders \\\n -H \"Authorization: Bearer $EMV_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Idempotency-Key: pedido-123\" \\\n -d '{\n \"customer\": {\n \"name\": \"Maria Silva\",\n \"email\": \"maria@exemplo.com\",\n \"document\": \"52998224725\",\n \"type\": \"individual\",\n \"phones\": { \"mobile_phone\": { \"country_code\": \"55\", \"area_code\": \"11\", \"number\": \"999999999\" } }\n },\n \"items\": [{ \"amount\": 10000, \"description\": \"Produto\", \"quantity\": 1, \"code\": \"SKU-1\" }],\n \"payments\": [{\n \"payment_method\": \"credit_card\",\n \"credit_card\": {\n \"card_token\": \"token_xxxxxxxx\",\n \"installments\": 1,\n \"billing_address\": {\n \"line_1\": \"100, Rua Exemplo, Centro\",\n \"zip_code\": \"01001000\",\n \"city\": \"Sao Paulo\",\n \"state\": \"SP\",\n \"country\": \"BR\"\n }\n }\n }]\n }'\n```\n\nValores sempre **em centavos** (`10000` = R$ 100,00). A resposta traz o pedido e a cobrança:\n\n```json\n{\n \"data\": {\n \"id\": \"ord_...\",\n \"status\": \"paid\",\n \"customer\": { \"id\": \"cust_...\", \"...\": \"...\" },\n \"charges\": [{\n \"id\": \"chg_...\",\n \"status\": \"paid\",\n \"card\": { \"id\": \"crd_...\", \"brand\": \"mastercard\", \"last_four_digits\": \"6931\", \"...\": \"...\" }\n }]\n }\n}\n```\n\n## Reutilizar o cartão (compra com 1 clique)\n\nTodo cartão usado em um pedido **fica salvo no cliente**. Guarde no seu banco o `customer.id` e o `charges[0].card.id` da resposta. Nas próximas compras, use o `card_id`. **Não é preciso tokenizar de novo** e o comprador não digita nada:\n\n```json\n{\n \"customer_id\": \"cust_...\",\n \"items\": [{ \"amount\": 10000, \"description\": \"Produto\", \"quantity\": 1, \"code\": \"SKU-1\" }],\n \"payments\": [{\n \"payment_method\": \"credit_card\",\n \"credit_card\": { \"card_id\": \"crd_...\", \"installments\": 1 }\n }]\n}\n```\n\nPara remover um cartão salvo (ex.: o comprador pediu), use `DELETE /Cards/:id`.\n\n| Situação | Envie |\n|---|---|\n| Cartão novo | `card_token` (tokenizado com o `emv.js`) |\n| Cartão já usado antes | `card_id` |\n| Cobrança recorrente / assinatura | `card_id` |\n\n## Erros do emv.js\n\n`tokenize` rejeita com um erro que tem `code` (para tratar no código), `message` (em português, para mostrar ao comprador) e `field` (o campo com problema, quando houver).\n\n| code | Quando acontece |\n|---|---|\n| `invalid_number`, `invalid_holder_name`, `invalid_expiry_month`, `invalid_expiry_year`, `expired_card`, `invalid_cvv` | Dado do cartão inválido (`field` indica o campo) |\n| `card_declined` | O cartão não pôde ser validado |\n| `unauthorized` | Chave pública inválida ou domínio não autorizado |\n| `insecure_context` | Chave de produção em página sem HTTPS |\n| `timeout`, `network_error`, `service_unavailable` | Falha temporária: pode tentar de novo |\n| `invalid_public_key` | `EMV()` recebeu algo que não é uma chave pública `pk_` |\n\n## Testar no sandbox\n\n- Use a chave `pk_test_...` (de `GET /Cards/publicKey` no sandbox) e a sua `gw_test_...`.\n- Cartão aprovado: `4000 0000 0000 0010`, qualquer nome, validade futura, CVV `123`.\n- Para simular **recusa**: use um CVV começando com `6` (ex.: `612`).\n- Nenhum valor é cobrado de verdade.\n\n## Regras de segurança\n\n- ✅ Carregue o script sempre de `https://js.emvtech.com.br/v1/emv.js`. Não copie o arquivo para o seu servidor: assim você recebe as correções automaticamente.\n- ✅ Use HTTPS na página de pagamento (obrigatório em produção).\n- ❌ Nunca envie número ou CVV do cartão para o seu backend ou para a API: ela recusa.\n- ❌ Nunca coloque a chave de API (`gw_...`) no front-end.\n- ❌ Não reutilize um `card_token`: tokenize a cada pagamento com cartão novo.\n\n# Webhooks: receber notificações\n\nPagamentos mudam de status depois da criação do pedido: o Pix é pago minutos depois, o boleto em até 3 dias, um cartão pode ser estornado ou contestado. Em vez de consultar a API repetidamente, cadastre uma URL e **nós avisamos o seu sistema** a cada mudança.\n\n## 1. Cadastrar a URL\n\nPelo painel (**Webhooks**) ou pela API:\n\n```bash\ncurl https://sandbox-pay.emvtech.com.br/Webhooks \\\n -H \"Authorization: Bearer $EMV_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"url\": \"https://sualoja.com.br/webhooks/emv\", \"events\": [\"*\"] }'\n```\n\n- A URL precisa ser **HTTPS** e pública.\n- `events`: `[\"*\"]` (todos), `[\"charge.*\"]` (todos de cobrança) ou tipos exatos, como `[\"charge.paid\", \"charge.refunded\"]`.\n- A resposta traz o **`secret`**, que **só aparece nesta resposta**. Guarde-o: ele serve para validar a assinatura. Se perder, gere outro no painel ou com `POST /Webhooks/rotateSecret/:id`.\n\n## 2. O que chega na sua URL\n\nUm `POST` com o evento no corpo:\n\n```json\n{\n \"id\": \"evt_...\",\n \"object\": \"event\",\n \"type\": \"charge.paid\",\n \"livemode\": false,\n \"created_at\": \"2026-11-05T04:32:04.983Z\",\n \"data\": { \"id\": \"chg_...\", \"object\": \"charge\", \"status\": \"paid\", \"order_id\": \"ord_...\", \"amount\": 10000, \"...\": \"...\" }\n}\n```\n\n`data` é o objeto completo (a cobrança ou o pedido) no estado atual, no mesmo formato de `GET /Charges/:id` ou `GET /Orders/:id`.\n\nHeaders enviados:\n\n| Header | Conteúdo |\n|---|---|\n| `X-Gateway-Event` | Tipo do evento (ex.: `charge.paid`) |\n| `X-Gateway-Event-Id` | Id do evento (`evt_...`) |\n| `X-Gateway-Timestamp` | Momento do envio (Unix, em segundos) |\n| `X-Gateway-Signature` | `sha256=ASSINATURA` (veja o passo 3) |\n\n## 3. Validar a assinatura (obrigatório)\n\nQualquer um pode fazer um `POST` na sua URL. Para ter certeza de que a notificação veio de nós, calcule a assinatura e compare:\n\n```\nassinatura = HMAC-SHA256( secret, \".\" ) em hexadecimal\n```\n\nUse o **corpo bruto**, exatamente como chegou, antes de converter para JSON.\n\n### Node.js (Express)\n\n```js\nimport express from \"express\";\nimport crypto from \"node:crypto\";\n\nconst app = express();\nconst SECRET = process.env.EMV_WEBHOOK_SECRET;\n\n// express.raw: precisamos do corpo bruto para conferir a assinatura\napp.post(\"/webhooks/emv\", express.raw({ type: \"application/json\" }), (req, res) => {\n const timestamp = req.get(\"X-Gateway-Timestamp\");\n const received = (req.get(\"X-Gateway-Signature\") || \"\").replace(\"sha256=\", \"\");\n const expected = crypto.createHmac(\"sha256\", SECRET).update(`${timestamp}.${req.body}`).digest(\"hex\");\n\n const valid = received.length === expected.length\n && crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));\n const recent = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300; // até 5 min\n\n if (!valid || !recent) return res.status(401).end();\n\n const event = JSON.parse(req.body);\n // processe event.type / event.data (veja \"Boas práticas\")\n res.status(200).end();\n});\n```\n\n### PHP\n\n```php\n 300) {\n http_response_code(401);\n exit;\n}\n\n$event = json_decode($body, true);\n// processe $event['type'] / $event['data']\nhttp_response_code(200);\n```\n\n### Python (Flask)\n\n```python\nimport hmac, hashlib, os, time\nfrom flask import Flask, request, abort\n\napp = Flask(__name__)\nSECRET = os.environ[\"EMV_WEBHOOK_SECRET\"].encode()\n\n@app.post(\"/webhooks/emv\")\ndef webhook():\n body = request.get_data() # corpo bruto\n timestamp = request.headers.get(\"X-Gateway-Timestamp\", \"\")\n received = request.headers.get(\"X-Gateway-Signature\", \"\").replace(\"sha256=\", \"\")\n expected = hmac.new(SECRET, f\"{timestamp}.\".encode() + body, hashlib.sha256).hexdigest()\n\n if not hmac.compare_digest(expected, received) or abs(time.time() - int(timestamp or 0)) > 300:\n abort(401)\n\n event = request.get_json()\n # processe event[\"type\"] / event[\"data\"]\n return \"\", 200\n```\n\n## 4. Responder e novas tentativas\n\n- Responda **HTTP 2xx** rápido (em poucos segundos). Faça o processamento pesado depois, em fila.\n- Se a sua URL não responder 2xx, **tentamos de novo** após 1 min, 5 min, 30 min, 2 h, 6 h, 12 h e 24 h (8 tentativas, cerca de 2 dias). Depois disso, a entrega é dada como falha.\n- Para ver as entregas de um evento (tentativas, último status HTTP), use `GET /Events/:id`. Para reenviar, use o painel ou `POST /Events/resend/:id`.\n\n## 5. Boas práticas\n\n- **Idempotência:** o mesmo evento pode chegar mais de uma vez. Guarde o `id` (`evt_...`) dos eventos já processados e ignore repetidos.\n- **Ordem:** eventos podem chegar fora de ordem. Use o `status` em `data` (o estado atual) em vez de supor a sequência.\n- **Na dúvida, consulte:** se algo parecer estranho, busque o objeto na API (`GET /Charges/:id`) antes de agir.\n- **Cada ambiente tem seus webhooks:** cadastre a URL no sandbox e, de novo, em produção.\n\n# Referência\n\n## Status do pedido (`order.status`)\n\n| Status | Significado |\n|---|---|\n| `pending` | Aguardando pagamento (ex.: Pix ou boleto gerado, cartão só autorizado) |\n| `paid` | Pago |\n| `canceled` | Cancelado |\n| `failed` | Pagamento falhou (ex.: cartão recusado) |\n\n## Status da cobrança (`charge.status`)\n\n| Status | Significado |\n|---|---|\n| `pending` | Aguardando pagamento (Pix/boleto) |\n| `processing` | Em processamento |\n| `authorized` | Cartão autorizado, aguardando captura (`POST /Charges/capture/:id`) |\n| `paid` | Paga |\n| `partially_refunded` | Parte do valor estornada |\n| `refunded` | Estornada por completo |\n| `canceled` | Cancelada antes do pagamento |\n| `failed` | Recusada. O motivo vem em `failure.message` |\n| `chargedback` | Contestada pelo portador do cartão (chargeback) |\n| `overpaid` / `underpaid` | Pago valor acima / abaixo do esperado (boleto) |\n\n## Tipos de evento (webhooks)\n\nOs eventos seguem o formato `objeto.status` (ex.: `charge.paid`). São emitidos quando o status muda (exceto `pending` e `processing`).\n\n| Evento | Quando |\n|---|---|\n| `order.paid` | Pedido pago |\n| `order.canceled` | Pedido cancelado |\n| `order.failed` | Pagamento do pedido falhou |\n| `charge.authorized` | Cartão autorizado (aguardando captura) |\n| `charge.paid` | Cobrança paga. **É o evento para liberar o pedido** |\n| `charge.partially_refunded` | Estorno parcial |\n| `charge.refunded` | Estorno total |\n| `charge.canceled` | Cobrança cancelada |\n| `charge.failed` | Cobrança recusada |\n| `charge.chargedback` | Chargeback |\n| `charge.overpaid` / `charge.underpaid` | Valor pago diferente do esperado |\n\n## Erros da API\n\nTodo erro tem o mesmo formato:\n\n```json\n{\n \"error\": {\n \"statusCode\": 422,\n \"code\": \"validation_error\",\n \"title\": \"Validation failed\",\n \"detail\": \"Invalid request.\",\n \"errors\": [{ \"field\": \"items\", \"message\": \"Object items is required.\", \"code\": \"invalid_type\" }]\n }\n}\n```\n\nUse o `code` para tratar no seu código e o `detail` para entender o motivo. `errors` aparece em erros de validação, apontando o campo.\n\n| HTTP | `code` | Quando |\n|---|---|---|\n| 400 | `invalid_request` | Regra de negócio (ex.: valor maior que o saldo, cobrança já estornada) |\n| 401 | `unauthorized` | Chave de API ausente ou inválida |\n| 403 | `forbidden` | Chave de outro ambiente (ex.: `gw_live_` no sandbox) |\n| 404 | `not_found` | Recurso não existe (ou não é da sua empresa) |\n| 409 | `conflict` | Recurso duplicado |\n| 422 | `validation_error` | Campos inválidos ou ausentes (veja `errors`) |\n| 422 | `processor_rejected`, `refund_declined`... | Operação recusada no processamento (ex.: estorno negado) |\n| 500 | `internal_error` | Erro inesperado: tente de novo |\n| 502 | `processor_unavailable` | Processamento indisponível no momento: tente de novo |\n\nPara repetir com segurança uma requisição que deu erro de rede ou 5xx, reenvie com o **mesmo** `Idempotency-Key`: se a primeira tiver sido processada, você recebe a mesma resposta, sem cobrar de novo.\n\n## Regras importantes\n\n- **Valores em centavos:** `10000` = R$ 100,00.\n- **Itens:** cada item precisa de `amount`, `description`, `quantity` e `code`.\n- **Cliente:** envie `customer` (dados completos) ou `customer_id` (cliente já cadastrado).\n- **Cartão salvo (`card_id`):** o pedido precisa ter o `customer_id` do mesmo cliente dono do cartão.\n- **Boleto:** exige endereço do cliente (`customer.address`).\n- **Recebedor:** crie ao menos um antes do primeiro pedido. Sem `split` no pedido, o valor vai para o recebedor padrão (o primeiro criado; troque no painel).\n- **Ids:** cada objeto tem um prefixo: `cust_` (cliente), `crd_` (cartão), `rcp_` (recebedor), `ord_` (pedido), `chg_` (cobrança), `evt_` (evento), `whk_` (webhook), `lnk_` (link).\n\n## Limitações do sandbox\n\nO sandbox simula o processamento, sem dinheiro real. Algumas diferenças em relação à produção:\n\n- **Boleto:** temporariamente indisponível no sandbox (o pedido volta `failed`) por uma limitação do ambiente de testes. Em produção funciona normalmente.\n- **Pix:** é pago automaticamente alguns instantes após a criação (chega o evento `charge.paid`). O QR Code é ilustrativo.\n- **Estorno:** logo após o pagamento pode ser recusado (\"Valor inválido para estorno\"). Aguarde 1 a 2 minutos.\n- **Transferências:** o saldo das vendas demora para ficar disponível no sandbox, então `POST /Transfers` costuma responder saldo insuficiente.\n- **Recusa de cartão:** use um CVV começando com `6` (ex.: `612`).\n\n## Ir para produção\n\n1. Receba da EMV o endereço da API de produção e o acesso ao painel de produção.\n2. Gere a chave `gw_live_...` no painel de produção (**Configurações**).\n3. Cadastre os recebedores com dados reais (CPF/CNPJ e conta bancária).\n4. Cadastre a URL de webhook de produção e guarde o novo `secret`.\n5. No checkout, use a `public_key` de produção (`GET /Cards/publicKey` com a chave `gw_live_`). O script `emv.js` é o mesmo.\n6. Página de pagamento em **HTTPS** (obrigatório em produção)."
},
"servers": [
{
"url": "https://sandbox-pay.emvtech.com.br",
"description": "Sandbox (testes)"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "Recebedores",
"description": "Quem recebe o dinheiro das vendas (split). Crie ao menos um antes do primeiro pedido: o primeiro recebedor vira o padrão (recebe as vendas sem `split`). O recebedor padrão pode ser trocado no painel."
},
{
"name": "Clientes",
"description": "O comprador. Você pode cadastrar antes (`customer_id` no pedido) ou enviar os dados direto no pedido (`customer`): nesse caso o cliente é criado automaticamente e o `id` vem na resposta."
},
{
"name": "Cartões",
"description": "Cartões salvos do cliente. Todo cartão usado em um pedido fica salvo automaticamente. Para tokenizar o cartão no seu checkout, veja **Como pagar com cartão**."
},
{
"name": "Pedidos",
"description": "Venda com um ou mais pagamentos (cartão, Pix ou boleto). Pedidos com cartão usam `card_token` (cartão novo, tokenizado com o emv.js) ou `card_id` (cartão já salvo)."
},
{
"name": "Cobranças",
"description": "Cada pagamento de um pedido é uma cobrança (`chg_...`): é nela que se captura e estorna."
},
{
"name": "Transferências",
"description": "Saque do saldo disponível de um recebedor para a conta bancária dele."
},
{
"name": "Links de pagamento",
"description": "Link pronto para enviar ao comprador, com página de pagamento da EMV."
},
{
"name": "Webhooks e eventos",
"description": "Notificações enviadas ao seu sistema a cada mudança de status. Veja **Webhooks: receber notificações**. Os webhooks também podem ser cadastrados, listados e removidos no painel."
}
],
"paths": {
"/Recipients": {
"post": {
"tags": [
"Recebedores"
],
"summary": "Criar recebedor",
"operationId": "postRecipients",
"description": "Cadastra quem recebe o dinheiro das vendas, com os dados bancários. O primeiro recebedor da empresa vira o padrão.",
"parameters": [
{
"$ref": "#/components/parameters/IdempotencyKey"
}
],
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"example": {
"data": {
"id": "rcp_034s7g7fc91lTAG88MjDK4",
"object": "recipient",
"name": "Lojista Parceiro",
"email": "lojista@example.com",
"document": "52998224725",
"type": "individual",
"status": "active",
"default": false,
"fees_due_amount": 0,
"bank_account": {
"holder_name": "Lojista Parceiro",
"bank": "341",
"branch_number": "1234",
"account_last_digits": "2345",
"type": "checking"
},
"livemode": false,
"created_at": "2026-11-05T04:31:10.626Z"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": {}
},
"example": {
"name": "Lojista Parceiro",
"email": "lojista@example.com",
"document": "52998224725",
"type": "individual",
"default_bank_account": {
"holder_name": "Lojista Parceiro",
"holder_type": "individual",
"holder_document": "52998224725",
"bank": "341",
"branch_number": "1234",
"branch_check_digit": "6",
"account_number": "12345",
"account_check_digit": "6",
"type": "checking"
},
"transfer_settings": {
"transfer_enabled": false,
"transfer_interval": "Daily",
"transfer_day": 0
}
}
}
}
}
}
},
"/Recipients/{id}": {
"get": {
"tags": [
"Recebedores"
],
"summary": "Buscar recebedor",
"operationId": "getRecipientsId",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "rcp_034s7XjnEMwGEBoj4gEhBP"
}
],
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"example": {
"data": {
"id": "rcp_034s7g7fc91lTAG88MjDK4",
"object": "recipient",
"name": "Lojista Parceiro",
"email": "lojista@example.com",
"document": "52998224725",
"type": "individual",
"status": "active",
"default": false,
"fees_due_amount": 0,
"bank_account": {
"holder_name": "Lojista Parceiro",
"bank": "341",
"branch_number": "1234",
"account_last_digits": "2345",
"type": "checking"
},
"livemode": false,
"created_at": "2026-11-05T04:31:10.626Z"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/Recipients/balance/{id}": {
"get": {
"tags": [
"Recebedores"
],
"summary": "Saldo do recebedor",
"operationId": "getRecipientsBalanceId",
"description": "`available_amount` pode ser transferido agora; `waiting_funds_amount` ainda vai ser liberado (recebíveis futuros). Valores em centavos.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "rcp_034s7XjnEMwGEBoj4gEhBP"
}
],
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"example": {
"data": {
"object": "balance",
"recipient_id": "rcp_034s7g7fc91lTAG88MjDK4",
"available_amount": 0,
"waiting_funds_amount": 6436,
"transferred_amount": 0,
"fees_due_amount": 0,
"livemode": false
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/Customers": {
"post": {
"tags": [
"Clientes"
],
"summary": "Criar cliente",
"operationId": "postCustomers",
"parameters": [
{
"$ref": "#/components/parameters/IdempotencyKey"
}
],
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"example": {
"data": {
"id": "cust_034s7XreLCA8V6ybnl3Esv",
"object": "customer",
"name": "Cliente Teste",
"email": "cliente@example.com",
"document": "52998224725",
"type": "individual",
"phones": {
"mobile_phone": {
"number": "999999999",
"area_code": "11",
"country_code": "55"
}
},
"address": {
"id": "addr_xZRbp9vIgt4OrNW4",
"city": "Sao Paulo",
"state": "SP",
"line_1": "100, Rua Teste, Centro",
"status": "active",
"country": "BR",
"zip_code": "01001000",
"created_at": "2026-10-08T13:58:06Z",
"updated_at": "2026-11-05T04:29:32Z"
},
"metadata": null,
"livemode": false,
"created_at": "2026-11-05T04:25:44.967Z",
"updated_at": "2026-11-05T04:31:15.350Z"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"email": {
"type": "string",
"maxLength": 64,
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
},
"document": {
"type": "string",
"maxLength": 50
},
"type": {
"type": "string",
"enum": [
"individual",
"company"
]
},
"phones": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"address": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"metadata": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"required": [
"name"
],
"additionalProperties": {}
},
"example": {
"name": "Cliente Teste",
"email": "cliente@example.com",
"document": "52998224725",
"type": "individual",
"phones": {
"mobile_phone": {
"country_code": "55",
"area_code": "11",
"number": "999999999"
}
},
"address": {
"line_1": "100, Rua Teste, Centro",
"zip_code": "01001000",
"city": "Sao Paulo",
"state": "SP",
"country": "BR"
}
}
}
}
}
}
},
"/Customers/{id}": {
"get": {
"tags": [
"Clientes"
],
"summary": "Buscar cliente",
"operationId": "getCustomersId",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "cust_034s7XreLCA8V6ybnl3Esv"
}
],
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"example": {
"data": {
"id": "cust_034s7XreLCA8V6ybnl3Esv",
"object": "customer",
"name": "Cliente Teste",
"email": "cliente@example.com",
"document": "52998224725",
"type": "individual",
"phones": {
"mobile_phone": {
"number": "999999999",
"area_code": "11",
"country_code": "55"
}
},
"address": {
"id": "addr_xZRbp9vIgt4OrNW4",
"city": "Sao Paulo",
"state": "SP",
"line_1": "100, Rua Teste, Centro",
"status": "active",
"country": "BR",
"zip_code": "01001000",
"created_at": "2026-10-08T13:58:06Z",
"updated_at": "2026-11-05T04:29:32Z"
},
"metadata": null,
"livemode": false,
"created_at": "2026-11-05T04:25:44.967Z",
"updated_at": "2026-11-05T04:31:15.350Z"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"put": {
"tags": [
"Clientes"
],
"summary": "Atualizar cliente",
"operationId": "putCustomersId",
"description": "Envie só os campos que mudaram.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "cust_034s7XreLCA8V6ybnl3Esv"
},
{
"$ref": "#/components/parameters/IdempotencyKey"
}
],
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"example": {
"data": {
"id": "cust_034s7XreLCA8V6ybnl3Esv",
"object": "customer",
"name": "Cliente Teste Atualizado",
"email": "cliente@example.com",
"document": "52998224725",
"type": "individual",
"phones": {
"mobile_phone": {
"number": "999999999",
"area_code": "11",
"country_code": "55"
}
},
"address": {
"id": "addr_xZRbp9vIgt4OrNW4",
"city": "Sao Paulo",
"state": "SP",
"line_1": "100, Rua Teste, Centro",
"number": "100",
"status": "active",
"street": "Rua Teste",
"country": "BR",
"zip_code": "01001000",
"created_at": "2026-10-08T13:58:06Z",
"updated_at": "2026-11-05T04:31:20Z",
"neighborhood": "Centro"
},
"metadata": null,
"livemode": false,
"created_at": "2026-11-05T04:25:44.967Z",
"updated_at": "2026-11-05T04:31:20.548Z"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"email": {
"type": "string",
"maxLength": 64,
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
},
"document": {
"type": "string",
"maxLength": 50
},
"type": {
"type": "string",
"enum": [
"individual",
"company"
]
},
"phones": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"address": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"metadata": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"additionalProperties": {}
},
"example": {
"name": "Cliente Teste Atualizado"
}
}
}
}
}
},
"/Cards/publicKey": {
"get": {
"tags": [
"Cartões"
],
"summary": "Chave pública (tokenização)",
"operationId": "getCardsPublicKey",
"description": "Chave pública usada pelo **emv.js** para tokenizar o cartão no navegador. Não é segredo: pode ir para o front-end. Veja **Como pagar com cartão**.",
"parameters": [],
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"example": {
"data": {
"object": "public_key",
"public_key": "pk_test_xxxxxxxxxxxxxxxx",
"livemode": false
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/Cards": {
"post": {
"tags": [
"Cartões"
],
"summary": "Salvar cartão do cliente",
"operationId": "postCards",
"description": "Salva um cartão no cliente sem fazer uma compra (ex.: tela \"Meus cartões\"). O `token` vem do **emv.js**. A resposta traz o `id` (`crd_...`) para usar como `card_id` nos pedidos.",
"parameters": [
{
"$ref": "#/components/parameters/IdempotencyKey"
}
],
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"example": {
"data": {
"id": "crd_034s7gVkKOyRi2EdWUPrWR",
"object": "card",
"customer_id": "cust_034s7XreLCA8V6ybnl3Esv",
"brand": "Visa",
"first_six_digits": "400000",
"last_four_digits": "0010",
"holder_name": "TESTE POSTMAN",
"exp_month": 12,
"exp_year": 2030,
"type": "credit",
"status": "active",
"billing_address": {
"city": "Sao Paulo",
"state": "SP",
"line_1": "100, Rua Teste, Centro",
"country": "BR",
"zip_code": "01001000"
},
"livemode": false,
"created_at": "2026-11-05T04:31:25.939Z"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"customer_id": {
"type": "string"
},
"token": {
"type": "string",
"pattern": "^token_[A-Za-z0-9]+$"
},
"billing_address": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"customer_id",
"token"
]
},
"example": {
"customer_id": "cust_034s7XreLCA8V6ybnl3Esv",
"token": "token_xxxxxxxxxxxxxxxx",
"billing_address": {
"line_1": "100, Rua Teste, Centro",
"zip_code": "01001000",
"city": "Sao Paulo",
"state": "SP",
"country": "BR"
}
}
}
}
}
}
},
"/Cards/{id}": {
"get": {
"tags": [
"Cartões"
],
"summary": "Buscar cartão",
"operationId": "getCardsId",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "crd_034s7gVkKOyRi2EdWUPrWR"
}
],
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"example": {
"data": {
"id": "crd_034s7gVkKOyRi2EdWUPrWR",
"object": "card",
"customer_id": "cust_034s7XreLCA8V6ybnl3Esv",
"brand": "Visa",
"first_six_digits": "400000",
"last_four_digits": "0010",
"holder_name": "TESTE POSTMAN",
"exp_month": 12,
"exp_year": 2030,
"type": "credit",
"status": "active",
"billing_address": {
"city": "Sao Paulo",
"state": "SP",
"line_1": "100, Rua Teste, Centro",
"country": "BR",
"zip_code": "01001000"
},
"livemode": false,
"created_at": "2026-11-05T04:31:25.939Z"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
},
"delete": {
"tags": [
"Cartões"
],
"summary": "Remover cartão",
"operationId": "deleteCardsId",
"description": "Remove o cartão salvo do cliente: ele não pode mais ser cobrado pelo `card_id`. O registro continua no histórico dos pedidos.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "crd_034s7gVkKOyRi2EdWUPrWR"
},
{
"$ref": "#/components/parameters/IdempotencyKey"
}
],
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"example": {
"data": {
"id": "crd_034s7gVkKOyRi2EdWUPrWR",
"object": "card",
"customer_id": "cust_034s7XreLCA8V6ybnl3Esv",
"brand": "Visa",
"first_six_digits": "400000",
"last_four_digits": "0010",
"holder_name": "TESTE POSTMAN",
"exp_month": 12,
"exp_year": 2030,
"type": "credit",
"status": "deleted",
"billing_address": {
"city": "Sao Paulo",
"state": "SP",
"line_1": "100, Rua Teste, Centro",
"country": "BR",
"zip_code": "01001000"
},
"livemode": false,
"created_at": "2026-11-05T04:31:25.939Z"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
}
}
}
},
"/Orders": {
"post": {
"tags": [
"Pedidos"
],
"summary": "Criar pedido",
"operationId": "postOrders",
"description": "Cria a venda e processa o pagamento. Veja os exemplos de corpo (cartão, parcelado, só autorizar, cartão salvo, Pix, boleto, split).\n\n- **Cliente:** `customer` (dados completos) ou `customer_id`.\n- **Cartão:** `card_token` (cartão novo, do emv.js) ou `card_id` (cartão salvo; exige o `customer_id` do dono do cartão).\n- **Só autorizar:** `\"capture\": false` no cartão; capture depois em `POST /Charges/capture/{id}`.\n- **Pix:** a resposta traz `qr_code` (copia e cola) e `qr_code_url` (imagem). O pagamento chega pelo webhook `charge.paid`.\n- **Boleto:** exige endereço do cliente. Temporariamente indisponível no sandbox.\n- **Split:** sem `split`, o valor vai para o recebedor padrão.\n- Valores em centavos. Use o header `Idempotency-Key` para não criar o pedido duas vezes.",
"parameters": [
{
"$ref": "#/components/parameters/IdempotencyKey"
}
],
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"example": {
"data": {
"id": "ord_034s7ggIu9XeSpHeYMOZ3B",
"object": "order",
"code": "VY9WI0H64Z",
"status": "paid",
"amount": 10000,
"currency": "BRL",
"customer": {
"id": "cust_034s7XreLCA8V6ybnl3Esv",
"object": "customer",
"name": "Cliente Teste",
"email": "cliente@example.com",
"document": "52998224725",
"type": "individual",
"phones": {
"mobile_phone": {
"number": "999999999",
"area_code": "11",
"country_code": "55"
}
},
"address": {
"id": "addr_xZRbp9vIgt4OrNW4",
"city": "Sao Paulo",
"state": "SP",
"line_1": "100, Rua Teste, Centro",
"status": "active",
"country": "BR",
"zip_code": "01001000",
"created_at": "2026-10-08T13:58:06Z",
"updated_at": "2026-11-05T04:31:30Z"
},
"metadata": null,
"livemode": false,
"created_at": "2026-11-05T04:25:44.967Z",
"updated_at": "2026-11-05T04:31:32.651Z"
},
"items": [
{
"code": "SKU-1",
"amount": 10000,
"quantity": 1,
"description": "Produto Teste"
}
],
"shipping": null,
"charges": [
{
"id": "chg_034s7ggJsgZsz4KOLhznpj",
"object": "charge",
"order_id": "ord_034s7ggIu9XeSpHeYMOZ3B",
"status": "paid",
"payment_method": "credit_card",
"amount": 10000,
"paid_amount": 10000,
"refunded_amount": 0,
"installments": 1,
"card": {
"id": "crd_034s7gVkKOyRi2EdWUPrWR",
"object": "card",
"customer_id": "cust_034s7XreLCA8V6ybnl3Esv",
"brand": "Visa",
"first_six_digits": "400000",
"last_four_digits": "0010",
"holder_name": "TESTE POSTMAN",
"exp_month": 12,
"exp_year": 2030,
"type": "credit",
"status": "active",
"billing_address": {
"city": "Sao Paulo",
"state": "SP",
"line_1": "100, Rua Teste, Centro",
"country": "BR",
"zip_code": "01001000"
},
"livemode": false,
"created_at": "2026-11-05T04:31:25.939Z"
},
"pix": null,
"boleto": null,
"failure": null,
"split": [
{
"type": "recipient",
"recipient_id": "rcp_034k41lE3ek1EttRKs6yLj",
"amount": 9750
},
{
"type": "platform_fee",
"amount": 250
}
],
"last_transaction": {
"id": "txn_034s7ggKx7L9SPDvDOiaP1",
"object": "transaction",
"type": "credit_card",
"operation": "auth_and_capture",
"status": "captured",
"success": true,
"amount": 10000,
"installments": 1,
"authorization_code": "412780",
"nsu": "2213892380",
"tid": "2213892380",
"return_code": "0000",
"message": "Transação aprovada com sucesso",
"antifraud": {
"status": "approved",
"score": "moderated"
},
"created_at": "2026-11-05T04:31:32.675Z"
},
"livemode": false,
"paid_at": "2026-11-05T04:31:32.000Z",
"created_at": "2026-11-05T04:31:32.664Z",
"updated_at": "2026-11-05T04:31:33.078Z"
}
],
"metadata": {
"pedido": "123"
},
"livemode": false,
"created_at": "2026-11-05T04:31:32.654Z",
"updated_at": "2026-11-05T04:31:32.654Z"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string",
"maxLength": 52
},
"items": {
"minItems": 1,
"type": "array",
"items": {
"type": "object",
"properties": {
"amount": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"description": {
"type": "string",
"minLength": 1
},
"quantity": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"code": {
"type": [
"string",
"number"
]
}
},
"required": [
"amount",
"description",
"quantity"
],
"additionalProperties": {}
}
},
"customer_id": {
"type": "string"
},
"customer": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"payments": {
"minItems": 1,
"type": "array",
"items": {
"type": "object",
"properties": {
"payment_method": {
"type": "string",
"enum": [
"credit_card",
"debit_card",
"pix",
"boleto"
]
},
"amount": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"credit_card": {
"type": "object",
"properties": {
"card_id": {
"type": "string"
},
"card_token": {
"type": "string",
"pattern": "^token_[A-Za-z0-9]+$"
},
"installments": {
"default": 1,
"type": "integer",
"minimum": 1,
"maximum": 24
},
"statement_descriptor": {
"type": "string",
"maxLength": 13
},
"capture": {
"type": "boolean"
},
"billing_address": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"additionalProperties": {}
},
"debit_card": {
"type": "object",
"properties": {
"card_id": {
"type": "string"
},
"card_token": {
"type": "string",
"pattern": "^token_[A-Za-z0-9]+$"
},
"installments": {
"default": 1,
"type": "integer",
"minimum": 1,
"maximum": 24
},
"statement_descriptor": {
"type": "string",
"maxLength": 13
},
"capture": {
"type": "boolean"
},
"billing_address": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"additionalProperties": {}
},
"pix": {
"type": "object",
"properties": {
"expires_in": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"additionalProperties": {}
},
"boleto": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"split": {
"minItems": 1,
"type": "array",
"items": {
"type": "object",
"properties": {
"recipient_id": {
"type": "string"
},
"amount": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"options": {
"type": "object",
"properties": {
"liable": {
"type": "boolean"
},
"charge_processing_fee": {
"type": "boolean"
},
"charge_remainder_fee": {
"type": "boolean"
}
}
}
},
"required": [
"recipient_id"
]
}
}
},
"required": [
"payment_method"
],
"additionalProperties": {}
}
},
"shipping": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"closed": {
"type": "boolean"
},
"metadata": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"required": [
"items",
"payments"
],
"additionalProperties": {}
},
"examples": {
"Pedido - cartão": {
"summary": "Pedido - cartão",
"value": {
"customer": {
"name": "Cliente Teste",
"email": "cliente@example.com",
"document": "52998224725",
"type": "individual",
"phones": {
"mobile_phone": {
"country_code": "55",
"area_code": "11",
"number": "999999999"
}
},
"address": {
"line_1": "100, Rua Teste, Centro",
"zip_code": "01001000",
"city": "Sao Paulo",
"state": "SP",
"country": "BR"
}
},
"items": [
{
"amount": 10000,
"description": "Produto Teste",
"quantity": 1,
"code": "SKU-1"
}
],
"payments": [
{
"payment_method": "credit_card",
"credit_card": {
"card_token": "token_xxxxxxxxxxxxxxxx",
"installments": 1,
"billing_address": {
"line_1": "100, Rua Teste, Centro",
"zip_code": "01001000",
"city": "Sao Paulo",
"state": "SP",
"country": "BR"
}
}
}
],
"metadata": {
"pedido": "123"
}
}
},
"Pedido - cartão parcelado 3x": {
"summary": "Pedido - cartão parcelado 3x",
"value": {
"customer": {
"name": "Cliente Teste",
"email": "cliente@example.com",
"document": "52998224725",
"type": "individual",
"phones": {
"mobile_phone": {
"country_code": "55",
"area_code": "11",
"number": "999999999"
}
},
"address": {
"line_1": "100, Rua Teste, Centro",
"zip_code": "01001000",
"city": "Sao Paulo",
"state": "SP",
"country": "BR"
}
},
"items": [
{
"amount": 10000,
"description": "Produto Teste",
"quantity": 1,
"code": "SKU-1"
}
],
"payments": [
{
"payment_method": "credit_card",
"credit_card": {
"card_token": "token_xxxxxxxxxxxxxxxx",
"installments": 3,
"billing_address": {
"line_1": "100, Rua Teste, Centro",
"zip_code": "01001000",
"city": "Sao Paulo",
"state": "SP",
"country": "BR"
}
}
}
]
}
},
"Pedido - cartão só autorizar (capturar depois)": {
"summary": "Pedido - cartão só autorizar (capturar depois)",
"value": {
"customer": {
"name": "Cliente Teste",
"email": "cliente@example.com",
"document": "52998224725",
"type": "individual",
"phones": {
"mobile_phone": {
"country_code": "55",
"area_code": "11",
"number": "999999999"
}
},
"address": {
"line_1": "100, Rua Teste, Centro",
"zip_code": "01001000",
"city": "Sao Paulo",
"state": "SP",
"country": "BR"
}
},
"items": [
{
"amount": 10000,
"description": "Produto Teste",
"quantity": 1,
"code": "SKU-1"
}
],
"payments": [
{
"payment_method": "credit_card",
"credit_card": {
"card_token": "token_xxxxxxxxxxxxxxxx",
"installments": 1,
"billing_address": {
"line_1": "100, Rua Teste, Centro",
"zip_code": "01001000",
"city": "Sao Paulo",
"state": "SP",
"country": "BR"
},
"capture": false
}
}
]
}
},
"Pedido - cartão salvo (card_id)": {
"summary": "Pedido - cartão salvo (card_id)",
"value": {
"customer_id": "cust_034s7XreLCA8V6ybnl3Esv",
"items": [
{
"amount": 10000,
"description": "Produto Teste",
"quantity": 1,
"code": "SKU-1"
}
],
"payments": [
{
"payment_method": "credit_card",
"credit_card": {
"card_id": "crd_034s7gVkKOyRi2EdWUPrWR",
"installments": 1
}
}
]
}
},
"Pedido - Pix": {
"summary": "Pedido - Pix",
"value": {
"customer": {
"name": "Cliente Teste",
"email": "cliente@example.com",
"document": "52998224725",
"type": "individual",
"phones": {
"mobile_phone": {
"country_code": "55",
"area_code": "11",
"number": "999999999"
}
},
"address": {
"line_1": "100, Rua Teste, Centro",
"zip_code": "01001000",
"city": "Sao Paulo",
"state": "SP",
"country": "BR"
}
},
"items": [
{
"amount": 10000,
"description": "Produto Teste",
"quantity": 1,
"code": "SKU-1"
}
],
"payments": [
{
"payment_method": "pix",
"pix": {
"expires_in": 3600
}
}
]
}
},
"Pedido - boleto": {
"summary": "Pedido - boleto",
"value": {
"customer": {
"name": "Cliente Teste",
"email": "cliente@example.com",
"document": "52998224725",
"type": "individual",
"phones": {
"mobile_phone": {
"country_code": "55",
"area_code": "11",
"number": "999999999"
}
},
"address": {
"line_1": "100, Rua Teste, Centro",
"zip_code": "01001000",
"city": "Sao Paulo",
"state": "SP",
"country": "BR"
}
},
"items": [
{
"amount": 10000,
"description": "Produto Teste",
"quantity": 1,
"code": "SKU-1"
}
],
"payments": [
{
"payment_method": "boleto",
"boleto": {
"instructions": "Nao receber apos o vencimento"
}
}
]
}
},
"Pedido - cartão com split": {
"summary": "Pedido - cartão com split",
"value": {
"customer": {
"name": "Cliente Teste",
"email": "cliente@example.com",
"document": "52998224725",
"type": "individual",
"phones": {
"mobile_phone": {
"country_code": "55",
"area_code": "11",
"number": "999999999"
}
},
"address": {
"line_1": "100, Rua Teste, Centro",
"zip_code": "01001000",
"city": "Sao Paulo",
"state": "SP",
"country": "BR"
}
},
"items": [
{
"amount": 10000,
"description": "Produto Teste",
"quantity": 1,
"code": "SKU-1"
}
],
"payments": [
{
"payment_method": "credit_card",
"credit_card": {
"card_token": "token_xxxxxxxxxxxxxxxx",
"installments": 1,
"billing_address": {
"line_1": "100, Rua Teste, Centro",
"zip_code": "01001000",
"city": "Sao Paulo",
"state": "SP",
"country": "BR"
}
},
"split": [
{
"recipient_id": "rcp_034s7XjnEMwGEBoj4gEhBP"
}
]
}
]
}
}
}
}
}
}
}
},
"/Orders/{id}": {
"get": {
"tags": [
"Pedidos"
],
"summary": "Buscar pedido",
"operationId": "getOrdersId",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "ord_034s7gvDVKQJPF4fbUgRNZ"
}
],
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"example": {
"data": {
"id": "ord_034s7hI2chLikUfKTgukyV",
"object": "order",
"code": "WVZOHKET15",
"status": "paid",
"amount": 10000,
"currency": "BRL",
"customer": {
"id": "cust_034s7XreLCA8V6ybnl3Esv",
"object": "customer",
"name": "Cliente Teste",
"email": "cliente@example.com",
"document": "52998224725",
"type": "individual",
"phones": {
"mobile_phone": {
"number": "999999999",
"area_code": "11",
"country_code": "55"
}
},
"address": {
"id": "addr_xZRbp9vIgt4OrNW4",
"city": "Sao Paulo",
"state": "SP",
"line_1": "100, Rua Teste, Centro",
"status": "active",
"country": "BR",
"zip_code": "01001000",
"created_at": "2026-10-08T13:58:06Z",
"updated_at": "2026-11-05T04:31:30Z"
},
"metadata": null,
"livemode": false,
"created_at": "2026-11-05T04:25:44.967Z",
"updated_at": "2026-11-05T04:31:56.653Z"
},
"items": [
{
"code": "SKU-1",
"amount": 10000,
"quantity": 1,
"description": "Produto Teste"
}
],
"shipping": null,
"charges": [
{
"id": "chg_034s7hI3hEquBAAYNr78Vm",
"object": "charge",
"order_id": "ord_034s7hI2chLikUfKTgukyV",
"status": "paid",
"payment_method": "credit_card",
"amount": 10000,
"paid_amount": 10000,
"refunded_amount": 0,
"installments": 1,
"card": {
"id": "crd_034s7gVkKOyRi2EdWUPrWR",
"object": "card",
"customer_id": "cust_034s7XreLCA8V6ybnl3Esv",
"brand": "Visa",
"first_six_digits": "400000",
"last_four_digits": "0010",
"holder_name": "TESTE POSTMAN",
"exp_month": 12,
"exp_year": 2030,
"type": "credit",
"status": "active",
"billing_address": {
"city": "Sao Paulo",
"state": "SP",
"line_1": "100, Rua Teste, Centro",
"country": "BR",
"zip_code": "01001000"
},
"livemode": false,
"created_at": "2026-11-05T04:31:25.939Z"
},
"pix": null,
"boleto": null,
"failure": null,
"split": [
{
"type": "recipient",
"recipient_id": "rcp_034s7g7fc91lTAG88MjDK4",
"amount": 9750
},
{
"type": "platform_fee",
"amount": 250
}
],
"last_transaction": {
"id": "txn_034s7hI3zJR4QTKvNBpWq7",
"object": "transaction",
"type": "credit_card",
"operation": "auth_and_capture",
"status": "captured",
"success": true,
"amount": 10000,
"installments": 1,
"authorization_code": "971666",
"nsu": "2213892384",
"tid": "2213892384",
"return_code": "0000",
"message": "Transação aprovada com sucesso",
"antifraud": {
"status": "approved",
"score": "moderated"
},
"created_at": "2026-11-05T04:31:56.670Z"
},
"livemode": false,
"paid_at": "2026-11-05T04:31:56.000Z",
"created_at": "2026-11-05T04:31:56.667Z",
"updated_at": "2026-11-05T04:31:56.985Z"
}
],
"metadata": null,
"livemode": false,
"created_at": "2026-11-05T04:31:56.657Z",
"updated_at": "2026-11-05T04:31:56.657Z"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/Charges/{id}": {
"get": {
"tags": [
"Cobranças"
],
"summary": "Buscar cobrança",
"operationId": "getChargesId",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "chg_034s7gvEZqjNfHyfiCkBxf"
}
],
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"example": {
"data": {
"id": "chg_034s7hI3hEquBAAYNr78Vm",
"object": "charge",
"order_id": "ord_034s7hI2chLikUfKTgukyV",
"status": "paid",
"payment_method": "credit_card",
"amount": 10000,
"paid_amount": 10000,
"refunded_amount": 0,
"installments": 1,
"card": {
"id": "crd_034s7gVkKOyRi2EdWUPrWR",
"object": "card",
"customer_id": "cust_034s7XreLCA8V6ybnl3Esv",
"brand": "Visa",
"first_six_digits": "400000",
"last_four_digits": "0010",
"holder_name": "TESTE POSTMAN",
"exp_month": 12,
"exp_year": 2030,
"type": "credit",
"status": "active",
"billing_address": {
"city": "Sao Paulo",
"state": "SP",
"line_1": "100, Rua Teste, Centro",
"country": "BR",
"zip_code": "01001000"
},
"livemode": false,
"created_at": "2026-11-05T04:31:25.939Z"
},
"pix": null,
"boleto": null,
"failure": null,
"split": [
{
"type": "recipient",
"recipient_id": "rcp_034s7g7fc91lTAG88MjDK4",
"amount": 9750
},
{
"type": "platform_fee",
"amount": 250
}
],
"last_transaction": {
"id": "txn_034s7hI3zJR4QTKvNBpWq7",
"object": "transaction",
"type": "credit_card",
"operation": "auth_and_capture",
"status": "captured",
"success": true,
"amount": 10000,
"installments": 1,
"authorization_code": "971666",
"nsu": "2213892384",
"tid": "2213892384",
"return_code": "0000",
"message": "Transação aprovada com sucesso",
"antifraud": {
"status": "approved",
"score": "moderated"
},
"created_at": "2026-11-05T04:31:56.670Z"
},
"livemode": false,
"paid_at": "2026-11-05T04:31:56.000Z",
"created_at": "2026-11-05T04:31:56.667Z",
"updated_at": "2026-11-05T04:31:56.985Z"
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
},
"/Charges/capture/{id}": {
"post": {
"tags": [
"Cobranças"
],
"summary": "Capturar cobrança",
"operationId": "postChargesCaptureId",
"description": "Captura uma cobrança de cartão `authorized` (pedido criado com `\"capture\": false`). Sem `amount`, captura o valor total; com `amount`, captura parcial.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "chg_034s7gvEZqjNfHyfiCkBxf"
},
{
"$ref": "#/components/parameters/IdempotencyKey"
}
],
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"example": {
"data": {
"id": "chg_034s7gvEZqjNfHyfiCkBxf",
"object": "charge",
"order_id": "ord_034s7gvDVKQJPF4fbUgRNZ",
"status": "paid",
"payment_method": "credit_card",
"amount": 10000,
"paid_amount": 10000,
"refunded_amount": 0,
"installments": 1,
"card": {
"id": "crd_034s7gVkKOyRi2EdWUPrWR",
"object": "card",
"customer_id": "cust_034s7XreLCA8V6ybnl3Esv",
"brand": "Visa",
"first_six_digits": "400000",
"last_four_digits": "0010",
"holder_name": "TESTE POSTMAN",
"exp_month": 12,
"exp_year": 2030,
"type": "credit",
"status": "active",
"billing_address": {
"city": "Sao Paulo",
"state": "SP",
"line_1": "100, Rua Teste, Centro",
"country": "BR",
"zip_code": "01001000"
},
"livemode": false,
"created_at": "2026-11-05T04:31:25.939Z"
},
"pix": null,
"boleto": null,
"failure": null,
"split": [
{
"type": "recipient",
"recipient_id": "rcp_034k41lE3ek1EttRKs6yLj",
"amount": 9750
},
{
"type": "platform_fee",
"amount": 250
}
],
"last_transaction": {
"id": "txn_034s7hUXggCPKbNn6Mvh3Z",
"object": "transaction",
"type": "credit_card",
"operation": "capture",
"status": "captured",
"success": true,
"amount": 10000,
"installments": 1,
"authorization_code": "557893",
"nsu": "2213892382",
"tid": "2213892382",
"return_code": "0000",
"message": "Transação aprovada com sucesso",
"antifraud": {
"status": "approved",
"score": "moderated"
},
"created_at": "2026-11-05T04:32:04.607Z"
},
"livemode": false,
"paid_at": "2026-11-05T04:32:04.000Z",
"created_at": "2026-11-05T04:31:42.150Z",
"updated_at": "2026-11-05T04:32:04.966Z"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
}
},
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"amount": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
},
"example": {}
}
}
}
}
},
"/Charges/refund/{id}": {
"post": {
"tags": [
"Cobranças"
],
"summary": "Estornar cobrança",
"operationId": "postChargesRefundId",
"description": "Estorna a cobrança. Sem `amount`, estorna o que falta; com `amount`, estorno parcial. No sandbox, estorno logo depois do pagamento pode ser recusado: aguarde 1 a 2 minutos.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "chg_034s7gvEZqjNfHyfiCkBxf"
},
{
"$ref": "#/components/parameters/IdempotencyKey"
}
],
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"example": {
"data": {
"id": "chg_034s7hI3hEquBAAYNr78Vm",
"object": "charge",
"order_id": "ord_034s7hI2chLikUfKTgukyV",
"status": "partially_refunded",
"payment_method": "credit_card",
"amount": 10000,
"paid_amount": 10000,
"refunded_amount": 3000,
"installments": 1,
"card": {
"id": "crd_034s7gVkKOyRi2EdWUPrWR",
"object": "card",
"customer_id": "cust_034s7XreLCA8V6ybnl3Esv",
"brand": "Visa",
"first_six_digits": "400000",
"last_four_digits": "0010",
"holder_name": "TESTE POSTMAN",
"exp_month": 12,
"exp_year": 2030,
"type": "credit",
"status": "active",
"billing_address": {
"city": "Sao Paulo",
"state": "SP",
"line_1": "100, Rua Teste, Centro",
"country": "BR",
"zip_code": "01001000"
},
"livemode": false,
"created_at": "2026-11-05T04:31:25.939Z"
},
"pix": null,
"boleto": null,
"failure": null,
"split": [
{
"type": "recipient",
"recipient_id": "rcp_034s7g7fc91lTAG88MjDK4",
"amount": 9750
},
{
"type": "platform_fee",
"amount": 250
}
],
"last_transaction": {
"id": "txn_034s7ha0ovNPSP2LtoZyAB",
"object": "transaction",
"type": "credit_card",
"operation": "cancel",
"status": "partially_refunded",
"success": true,
"amount": 3000,
"installments": 1,
"authorization_code": "971666",
"nsu": "2213892384",
"tid": "2213892384",
"return_code": "0000",
"message": "Transação aprovada com sucesso",
"antifraud": {
"status": "approved",
"score": "moderated"
},
"created_at": "2026-11-05T04:32:08.086Z"
},
"livemode": false,
"paid_at": "2026-11-05T04:31:56.000Z",
"created_at": "2026-11-05T04:31:56.667Z",
"updated_at": "2026-11-05T04:32:08.401Z"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
}
},
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"amount": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
}
},
"examples": {
"Estornar parcial": {
"summary": "Estornar parcial",
"value": {
"amount": 3000
}
},
"Estornar total": {
"summary": "Estornar total",
"value": {}
}
}
}
}
}
}
},
"/Charges/qrcode/{id}": {
"get": {
"tags": [
"Cobranças"
],
"summary": "QR Code do Pix (imagem)",
"operationId": "getChargesQrcodeId",
"description": "Imagem PNG do QR Code do Pix, para exibir ao comprador (`![](\"...\")
`). Rota pública, sem chave de API: é o `qr_code_url` da cobrança.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "chg_034s7gvEZqjNfHyfiCkBxf"
}
],
"responses": {
"200": {
"description": "Arquivo",
"content": {
"image/png": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"security": []
}
},
"/Charges/boleto/{id}": {
"get": {
"tags": [
"Cobranças"
],
"summary": "PDF do boleto",
"operationId": "getChargesBoletoId",
"description": "PDF do boleto, para o comprador baixar ou imprimir. Rota pública, sem chave de API: é o `pdf_url` da cobrança.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "chg_034s7gvEZqjNfHyfiCkBxf"
}
],
"responses": {
"200": {
"description": "Arquivo",
"content": {
"application/pdf": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"security": []
}
},
"/Transfers": {
"post": {
"tags": [
"Transferências"
],
"summary": "Transferir",
"operationId": "postTransfers",
"description": "Transfere o saldo disponível (`available_amount` em `GET /Recipients/balance/{id}`) para a conta bancária do recebedor. No sandbox, o saldo demora para ficar disponível, então é comum receber saldo insuficiente.",
"parameters": [
{
"$ref": "#/components/parameters/IdempotencyKey"
}
],
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"recipient_id": {
"type": "string"
},
"amount": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"recipient_id",
"amount"
]
},
"example": {
"recipient_id": "rcp_034s7XjnEMwGEBoj4gEhBP",
"amount": 1000
}
}
}
}
}
},
"/PaymentLinks": {
"post": {
"tags": [
"Links de pagamento"
],
"summary": "Criar link",
"operationId": "postPaymentLinks",
"parameters": [
{
"$ref": "#/components/parameters/IdempotencyKey"
}
],
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"example": {
"data": {
"id": "lnk_034s7hyQ0MDl21fjFp2aYe",
"object": "payment_link",
"url": "https://checkout.emvtech.com.br/#/lnk_034s7hyQ0MDl21fjFp2aYe",
"name": "Curso Online",
"amount": 10000,
"recipient_id": "rcp_034k41lE3ek1EttRKs6yLj",
"items": [
{
"amount": 10000,
"quantity": 1,
"description": "Curso Online"
}
],
"payment_config": {
"accepted_payment_methods": [
"credit_card",
"pix"
]
},
"customer_config": null,
"active": true,
"livemode": false,
"created_at": "2026-11-05T04:32:23.609Z"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"amount": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"recipient_id": {
"type": "string"
},
"items": {
"minItems": 1,
"type": "array",
"items": {
"type": "object",
"properties": {
"amount": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"description": {
"type": "string",
"minLength": 1
},
"quantity": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"amount",
"description",
"quantity"
],
"additionalProperties": {}
}
},
"payment_config": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"customer_config": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"name",
"amount",
"items",
"payment_config"
]
},
"example": {
"name": "Curso Online",
"amount": 10000,
"items": [
{
"amount": 10000,
"description": "Curso Online",
"quantity": 1
}
],
"payment_config": {
"accepted_payment_methods": [
"credit_card",
"pix"
]
}
}
}
}
}
}
},
"/PaymentLinks/{id}": {
"get": {
"tags": [
"Links de pagamento"
],
"summary": "Ver link",
"operationId": "getPaymentLinksId",
"description": "Dados públicos do link (usados pela página de pagamento). Rota pública, sem chave de API.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "lnk_034s7ZgJH866J8OSL59HIR"
}
],
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"example": {
"data": {
"id": "lnk_034s7hyQ0MDl21fjFp2aYe",
"object": "payment_link",
"url": "https://checkout.emvtech.com.br/#/lnk_034s7hyQ0MDl21fjFp2aYe",
"name": "Curso Online",
"amount": 10000,
"recipient_id": "rcp_034k41lE3ek1EttRKs6yLj",
"items": [
{
"amount": 10000,
"quantity": 1,
"description": "Curso Online"
}
],
"payment_config": {
"accepted_payment_methods": [
"credit_card",
"pix"
]
},
"customer_config": null,
"active": true,
"livemode": false,
"created_at": "2026-11-05T04:32:23.609Z",
"public_key": "pk_test_xxxxxxxxxxxxxxxx"
}
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFound"
}
},
"security": []
}
},
"/Webhooks": {
"post": {
"tags": [
"Webhooks e eventos"
],
"summary": "Cadastrar webhook",
"operationId": "postWebhooks",
"description": "URL HTTPS e pública. `events`: `[\"*\"]`, `[\"charge.*\"]` ou tipos exatos. **O `secret` (para validar a assinatura) só aparece nesta resposta.**",
"parameters": [
{
"$ref": "#/components/parameters/IdempotencyKey"
}
],
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"example": {
"data": {
"id": "whk_034s7i5VjoyS4Gk7OEntDw",
"object": "webhook",
"url": "https://example.com/webhooks/gateway",
"events": [
"*"
],
"application_id": null,
"active": true,
"livemode": false,
"created_at": "2026-11-05T04:32:28.120Z",
"secret": "xxxxxxxxxxxxxxxx"
}
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"422": {
"$ref": "#/components/responses/Unprocessable"
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"maxLength": 2048,
"format": "uri"
},
"events": {
"default": [
"*"
],
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"pattern": "^(\\*|(order|charge)\\.(\\*|[a-z_]+))$"
}
},
"application_id": {
"type": "string",
"minLength": 1,
"maxLength": 64
}
},
"required": [
"url"
]
},
"example": {
"url": "https://example.com/webhooks/gateway",
"events": [
"*"
]
}
}
}
}
}
},
"/Events": {
"get": {
"tags": [
"Webhooks e eventos"
],
"summary": "Listar eventos",
"operationId": "getEvents",
"description": "Eventos da conta, do mais recente para o mais antigo. Útil para conferir o que foi enviado ou recuperar notificações perdidas.",
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"default": 20,
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "created_gte",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
{
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
}
]
}
},
{
"name": "created_lte",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
{
"type": "string",
"format": "date",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
}
]
}
},
{
"name": "type",
"in": "query",
"required": false,
"schema": {
"type": "string",
"pattern": "^(order|charge)\\.[a-z_]+$"
}
}
],
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"example": {
"data": [
{
"id": "evt_034s7hV8L8pcp3wz1ucWPE",
"object": "event",
"type": "charge.paid",
"livemode": false,
"created_at": "2026-11-05T04:32:04.983Z",
"data": {
"id": "chg_034s7gvEZqjNfHyfiCkBxf",
"pix": null,
"card": {
"id": "crd_034s7gVkKOyRi2EdWUPrWR",
"type": "credit",
"brand": "Visa",
"object": "card",
"status": "active",
"exp_year": 2030,
"livemode": false,
"exp_month": 12,
"created_at": "2026-11-05T04:31:25.939Z",
"customer_id": "cust_034s7XreLCA8V6ybnl3Esv",
"holder_name": "TESTE POSTMAN",
"billing_address": {
"city": "Sao Paulo",
"state": "SP",
"line_1": "100, Rua Teste, Centro",
"country": "BR",
"zip_code": "01001000"
},
"first_six_digits": "400000",
"last_four_digits": "0010"
},
"split": [
{
"type": "recipient",
"amount": 9750,
"recipient_id": "rcp_034k41lE3ek1EttRKs6yLj"
},
{
"type": "platform_fee",
"amount": 250
}
],
"amount": 10000,
"boleto": null,
"object": "charge",
"status": "paid",
"failure": null,
"paid_at": "2026-11-05T04:32:04.000Z",
"livemode": false,
"order_id": "ord_034s7gvDVKQJPF4fbUgRNZ",
"created_at": "2026-11-05T04:31:42.150Z",
"updated_at": "2026-11-05T04:32:04.966Z",
"paid_amount": 10000,
"installments": 1,
"payment_method": "credit_card",
"refunded_amount": 0,
"last_transaction": {
"id": "txn_034s7hUXggCPKbNn6Mvh3Z",
"nsu": "2213892382",
"tid": "2213892382",
"type": "credit_card",
"amount": 10000,
"object": "transaction",
"status": "captured",
"message": "Transação aprovada com sucesso",
"success": true,
"antifraud": {
"score": "moderated",
"status": "approved"
},
"operation": "capture",
"created_at": "2026-11-05T04:32:04.607Z",
"return_code": "0000",
"installments": 1,
"authorization_code": "557893"
}
},
"deliveries": []
},
{
"id": "evt_034s7hIZfTzQW51r5BLsNu",
"object": "event",
"type": "charge.paid",
"livemode": false,
"created_at": "2026-11-05T04:31:56.995Z",
"data": {
"id": "chg_034s7hI3hEquBAAYNr78Vm",
"pix": null,
"card": {
"id": "crd_034s7gVkKOyRi2EdWUPrWR",
"type": "credit",
"brand": "Visa",
"object": "card",
"status": "active",
"exp_year": 2030,
"livemode": false,
"exp_month": 12,
"created_at": "2026-11-05T04:31:25.939Z",
"customer_id": "cust_034s7XreLCA8V6ybnl3Esv",
"holder_name": "TESTE POSTMAN",
"billing_address": {
"city": "Sao Paulo",
"state": "SP",
"line_1": "100, Rua Teste, Centro",
"country": "BR",
"zip_code": "01001000"
},
"first_six_digits": "400000",
"last_four_digits": "0010"
},
"split": [
{
"type": "recipient",
"amount": 9750,
"recipient_id": "rcp_034s7g7fc91lTAG88MjDK4"
},
{
"type": "platform_fee",
"amount": 250
}
],
"amount": 10000,
"boleto": null,
"object": "charge",
"status": "paid",
"failure": null,
"paid_at": "2026-11-05T04:31:56.000Z",
"livemode": false,
"order_id": "ord_034s7hI2chLikUfKTgukyV",
"created_at": "2026-11-05T04:31:56.667Z",
"updated_at": "2026-11-05T04:31:56.985Z",
"paid_amount": 10000,
"installments": 1,
"payment_method": "credit_card",
"refunded_amount": 0,
"last_transaction": {
"id": "txn_034s7hI3zJR4QTKvNBpWq7",
"nsu": "2213892384",
"tid": "2213892384",
"type": "credit_card",
"amount": 10000,
"object": "transaction",
"status": "captured",
"message": "Transação aprovada com sucesso",
"success": true,
"antifraud": {
"score": "moderated",
"status": "approved"
},
"operation": "auth_and_capture",
"created_at": "2026-11-05T04:31:56.670Z",
"return_code": "0000",
"installments": 1,
"authorization_code": "971666"
}
},
"deliveries": []
}
],
"pagination": {
"has_more": false,
"next_cursor": null
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
}
}
}
},
"/Events/{id}": {
"get": {
"tags": [
"Webhooks e eventos"
],
"summary": "Buscar evento",
"operationId": "getEventsId",
"description": "O evento e as entregas aos seus webhooks (tentativas, último status HTTP, próxima tentativa).",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"example": "evt_034s7hV8L8pcp3wz1ucWPE"
}
],
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"example": {
"data": {
"id": "evt_034s7hV8L8pcp3wz1ucWPE",
"object": "event",
"type": "charge.paid",
"livemode": false,
"created_at": "2026-11-05T04:32:04.983Z",
"data": {
"id": "chg_034s7gvEZqjNfHyfiCkBxf",
"pix": null,
"card": {
"id": "crd_034s7gVkKOyRi2EdWUPrWR",
"type": "credit",
"brand": "Visa",
"object": "card",
"status": "active",
"exp_year": 2030,
"livemode": false,
"exp_month": 12,
"created_at": "2026-11-05T04:31:25.939Z",
"customer_id": "cust_034s7XreLCA8V6ybnl3Esv",
"holder_name": "TESTE POSTMAN",
"billing_address": {
"city": "Sao Paulo",
"state": "SP",
"line_1": "100, Rua Teste, Centro",
"country": "BR",
"zip_code": "01001000"
},
"first_six_digits": "400000",
"last_four_digits": "0010"
},
"split": [
{
"type": "recipient",
"amount": 9750,
"recipient_id": "rcp_034k41lE3ek1EttRKs6yLj"
},
{
"type": "platform_fee",
"amount": 250
}
],
"amount": 10000,
"boleto": null,
"object": "charge",
"status": "paid",
"failure": null,
"paid_at": "2026-11-05T04:32:04.000Z",
"livemode": false,
"order_id": "ord_034s7gvDVKQJPF4fbUgRNZ",
"created_at": "2026-11-05T04:31:42.150Z",
"updated_at": "2026-11-05T04:32:04.966Z",
"paid_amount": 10000,
"installments": 1,
"payment_method": "credit_card",
"refunded_amount": 0,
"last_transaction": {
"id": "txn_034s7hUXggCPKbNn6Mvh3Z",
"nsu": "2213892382",
"tid": "2213892382",
"type": "credit_card",
"amount": 10000,
"object": "transaction",
"status": "captured",
"message": "Transação aprovada com sucesso",
"success": true,
"antifraud": {
"score": "moderated",
"status": "approved"
},
"operation": "capture",
"created_at": "2026-11-05T04:32:04.607Z",
"return_code": "0000",
"installments": 1,
"authorization_code": "557893"
}
},
"deliveries": []
}
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Chave de API gerada no painel: `gw_test_...` (sandbox) ou `gw_live_...` (produção)."
}
},
"parameters": {
"IdempotencyKey": {
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Opcional, recomendado. Reenviar a mesma requisição com a mesma chave (em até 24 h) devolve a mesma resposta, sem criar ou cobrar de novo.",
"schema": {
"type": "string",
"maxLength": 255
},
"example": "pedido-123"
}
},
"schemas": {
"Error": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"statusCode": {
"type": "integer"
},
"code": {
"type": "string",
"description": "Código para tratar no seu sistema (ex.: `validation_error`, `not_found`)."
},
"title": {
"type": "string"
},
"detail": {
"type": "string",
"description": "Motivo do erro."
},
"errors": {
"type": "array",
"description": "Erros de validação por campo.",
"items": {
"type": "object"
}
}
}
}
}
}
},
"responses": {
"BadRequest": {
"description": "Regra de negócio (ex.: valor maior que o saldo, cobrança já estornada).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"Unauthorized": {
"description": "Chave de API ausente ou inválida.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"NotFound": {
"description": "Recurso não existe (ou não é da sua empresa).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"Unprocessable": {
"description": "Campos inválidos (veja `errors`) ou operação recusada no processamento.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"statusCode": 422,
"code": "validation_error",
"title": "Validation failed",
"detail": "Invalid request.",
"errors": [
{
"field": "items",
"message": "Object items is required.",
"code": "invalid_type"
}
]
}
}
}
}
}
}
}
}