# Introdução Receba pagamentos Pix no seu sistema com uma API simples e segura. Veja como funciona e por onde começar. A DuckFy recebe pagamentos Pix para a sua empresa. Você cria a cobrança pela API, o cliente paga com o app do banco e o valor entra no seu saldo. Depois você saca para a sua conta. ## Como um pagamento funciona 1. Seu servidor cria o pagamento com POST /v1/payments. 2. Você mostra o código Pix copia e cola (ou o link de pagamento) para o cliente. 3. O cliente paga no app do banco. 4. Nós confirmamos o pagamento e avisamos o seu sistema por webhook (https://docs.redeutopia.com/webhooks). 5. O valor, já sem a taxa, entra no seu saldo. Você saca quando quiser. ## Base URL Todas as chamadas usam esta base: Texto: ```text https://api.redeutopia.com/v1 ``` ## Por onde começar - Começar em 5 minutos (https://docs.redeutopia.com/comecar-em-5-minutos): crie a chave e o primeiro pagamento. - Autenticação (https://docs.redeutopia.com/autenticacao): chaves, escopos e onde guardar a chave. - Consultar o status da forma correta (https://docs.redeutopia.com/consultar-status): webhook primeiro, consulta como reforço. - Boas práticas de segurança (https://docs.redeutopia.com/seguranca): o que nunca fazer. ## Para ferramentas de IA - llms.txt (https://docs.redeutopia.com/llms.txt): índice das páginas em texto simples. - llms-full.txt (https://docs.redeutopia.com/llms-full.txt): toda a documentação em texto simples. - openapi.json (https://docs.redeutopia.com/openapi.json): o contrato da API em OpenAPI 3.1. --- # Começar em 5 minutos Crie uma chave de API, faça o primeiro pagamento Pix e receba a confirmação. ## 1. Crie a chave de API 1. Entre no painel em https://pay.redeutopia.com (https://pay.redeutopia.com). 2. Abra Integração > Chaves de API e clique em Nova chave. 3. Marque os escopos PAYMENT:CREATE e PAYMENT:READ. 4. Copie a chave. Ela aparece uma única vez. Guarde a chave numa variável de ambiente do seu servidor: cURL: ```bash export PAYMENTS_API_KEY='dk_000000000000_EXEMPLONAOUSE' ``` > Atenção: a chave fica só no servidor. Nunca coloque a chave no navegador, no aplicativo ou no repositório de código. ## 2. Cadastre o webhook Abra Integração > Webhooks no painel e cadastre a URL HTTPS do seu servidor que vai receber os avisos. Guarde o segredo de assinatura que aparece na criação. Veja Webhooks (https://docs.redeutopia.com/webhooks). ## 3. Crie o primeiro pagamento Faça a chamada do seu servidor. O valor vem do seu pedido, nunca do navegador. cURL: ```bash curl --request POST \ --url 'https://api.redeutopia.com/v1/payments' \ --header "Authorization: Bearer $PAYMENTS_API_KEY" \ --header 'Idempotency-Key: pedido-1234' \ --header 'Content-Type: application/json' \ --data '{"amount_cents": 15000, "external_id": "pedido-1234", "payer": {"name": "Maria Silva", "document": "12345678909"}}' ``` A resposta traz o id do pagamento, o status pending e o código Pix em pix.copy_paste. Guarde o id junto com o pedido. ## 4. Mostre o Pix ao cliente Mostre o código copia e cola na sua tela, ou envie o payment_url: é uma página pronta com QR Code e código copia e cola. ## 5. Receba a confirmação Quando o cliente pagar, você recebe o evento payment.paid no seu webhook. Só então libere o produto. Veja Consultar o status da forma correta (https://docs.redeutopia.com/consultar-status). --- # Autenticação Toda chamada usa uma chave de API no cabeçalho Authorization. Cada chave tem escopos que limitam o que ela pode fazer. ## Como enviar a chave Envie a chave no cabeçalho Authorization de toda requisição: Texto: ```text Authorization: Bearer dk_000000000000_EXEMPLONAOUSE ``` Sem chave, com chave errada ou revogada, a API responde 401 com o código unauthenticated. ## Escopos Cada chave só faz o que os seus escopos permitem. Dê a cada chave apenas os escopos que ela precisa. Sem o escopo, a API responde 403 com o código insufficient_scope. | Escopo | O que permite | | --- | --- | | PAYMENT:CREATE | Criar pagamentos Pix. | | PAYMENT:READ | Consultar e listar pagamentos. | | REFUND:CREATE | Pedir reembolsos. | | REFUND:READ | Consultar reembolsos. | | INFRACTION:READ | Consultar infrações. | | BALANCE:READ | Consultar o saldo. | | WITHDRAWAL:CREATE | Pedir saques. | | WITHDRAWAL:READ | Consultar saques. | | WEBHOOK:READ | Consultar endereços de webhook. | | WEBHOOK:WRITE | Cadastrar e desativar endereços de webhook. | ## Onde guardar a chave - Guarde a chave numa variável de ambiente ou num cofre de segredos do servidor. - Nunca coloque a chave no navegador, no aplicativo, no repositório de código ou em logs. - Use uma chave por sistema. Assim você revoga uma sem parar as outras. - Se a chave vazar, revogue no painel em Integração > Chaves de API e crie outra. > Atenção: a chave aparece uma única vez, na criação. Nós guardamos apenas uma assinatura dela e não conseguimos mostrá-la de novo. ## Chamadas do navegador A API recusa chamadas feitas de páginas web de outros sites (código origin_forbidden). Faça todas as chamadas a partir do seu servidor. --- # Criar um pagamento Pix Cria uma cobrança Pix e devolve o código copia e cola para o cliente pagar. Endpoint: POST https://api.redeutopia.com/v1/payments Escopo necessário: PAYMENT:CREATE Cabeçalho obrigatório: Idempotency-Key Envie o valor em centavos (ou os produtos do seu catálogo) e os dados de quem paga. A API calcula a taxa e devolve o pagamento com status pending e o código Pix em pix.copy_paste. > Atenção: calcule o valor no seu servidor, a partir do pedido. Nunca use um valor que veio do navegador. ## Requisição Cabeçalhos: Authorization, Content-Type: application/json e Idempotency-Key (obrigatório). Veja Idempotência (https://docs.redeutopia.com/idempotencia). | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | amount_cents | integer | um dos dois | Valor em centavos, número inteiro. Mínimo 100 (R$ 1,00). O máximo é o limite da sua conta. Envie amount_cents ou items, nunca os dois. | | items | array | um dos dois | Produtos do seu catálogo, até 50. Cada item tem product_id (o id do produto no painel) e qty (de 1 a 1000). Nós calculamos o total pelo preço cadastrado. | | payer | object | sim | Quem vai pagar. | | payer.name | string | sim | Nome de quem paga, até 120 caracteres. | | payer.document | string | sim | CPF (11 dígitos) ou CNPJ (14 dígitos) de quem paga. Com ou sem pontuação. | | description | string | não | Texto que o cliente vê no Pix, até 140 caracteres. Sem ele, usamos o nome da sua empresa. | | external_id | string | não | O id do pedido no seu sistema, até 120 caracteres. Não pode repetir. | | expires_in | integer | não | Validade em segundos, de 60 (1 minuto) a 604800 (7 dias). Padrão: 1800 (30 minutos). | | metadata | object | não | Até 20 pares chave e valor, em texto. Voltam iguais na resposta e nos webhooks. | ## Resposta A API responde 201 com o pagamento. | Campo | Tipo | Descrição | | --- | --- | --- | | id | string | Id do pagamento. Guarde junto com o pedido. | | status | string | Status do pagamento. Começa em pending. Veja os status (https://docs.redeutopia.com/consultar-status#status-do-pagamento). | | amount_cents | integer | Valor cobrado, em centavos. | | fee_cents | integer | Taxa da plataforma, em centavos. | | net_cents | integer | Valor que entra no seu saldo: amount_cents menos fee_cents. | | pix | object \| null | Dados do Pix. É null enquanto o código está sendo gerado e depois que o pagamento não pode mais ser pago. | | pix.copy_paste | string | Código Pix copia e cola. Mostre ao cliente. | | pix.qr_svg | string | QR Code do mesmo código, como imagem SVG pronta para mostrar ao cliente. Vem quando pix vem. | | expires_at | string (ISO 8601) \| null | Até quando o Pix pode ser pago. | | paid_at | string (ISO 8601) \| null | Quando o pagamento foi confirmado. null até lá. | | paid_late | boolean | true quando o pagamento chegou depois de expires_at. O valor entra no saldo do mesmo jeito. | | external_id | string \| null | O id do pedido que você enviou. | | description | string \| null | A descrição do Pix. | | customer | object \| null | Quem paga. | | customer.name | string | Nome de quem paga. | | customer.document | string | Documento de quem paga, mascarado. | | metadata | object | Os pares que você enviou. | | payment_url | string | Página pronta com QR Code e código copia e cola. Pode enviar ao cliente. | | created_at | string (ISO 8601) | Quando o pagamento foi criado. | > Dica: se pix vier null, o código ainda está sendo gerado. Ele chega no webhook ou em Buscar um pagamento (https://docs.redeutopia.com/buscar-pagamento) em poucos segundos. ## Erros | HTTP | Código | Quando acontece | O que fazer | | --- | --- | --- | --- | | 400 | idempotency_key_required | Faltou o cabeçalho Idempotency-Key. | Envie uma chave de 8 a 200 caracteres. | | 409 | duplicate_external_id | Já existe um pagamento com este external_id. | Busque o pagamento existente pela lista com external_id. | | 409 | idempotency_in_progress | A mesma chave ainda está sendo processada. | Espere um pouco e repita com a mesma chave. | | 422 | validation_failed | Algum campo está inválido. | Veja o campo fields da resposta. | | 422 | idempotency_key_reused | A chave já foi usada com outro corpo. | Use uma chave nova para um pedido novo. | | 503 | payments_unavailable | Pix está temporariamente indisponível. | Tente de novo em alguns minutos, com a mesma chave. | Exemplo de corpo da requisição: ```json { "amount_cents": 15000, "description": "Pedido 1234", "external_id": "pedido-1234", "expires_in": 1800, "payer": { "name": "Maria Silva", "document": "12345678909" }, "metadata": { "order_id": "1234" } } ``` Exemplo de resposta (201): ```json { "id": "0b5c1f7e-4a8d-4f2b-9c3e-6d7a8b9c0d1e", "status": "pending", "amount_cents": 15000, "fee_cents": 1050, "net_cents": 13950, "pix": { "copy_paste": "00020101021226870014br.gov.bcb.pix...6304ABCD" }, "expires_at": "2026-11-22T15:30:00Z", "paid_at": null, "paid_late": false, "external_id": "pedido-1234", "description": "Pedido 1234", "customer": { "name": "Maria Silva", "document": "***.***.***-09" }, "metadata": { "order_id": "1234" }, "payment_url": "https://pay.redeutopia.com/pay/0b5c1f7e-4a8d-4f2b-9c3e-6d7a8b9c0d1e", "created_at": "2026-11-22T15:00:00Z" } ``` Exemplo com cURL: ```bash curl --request POST \ --url 'https://api.redeutopia.com/v1/payments' \ --header "Authorization: Bearer $PAYMENTS_API_KEY" \ --header 'Idempotency-Key: pedido-1234' \ --header 'Content-Type: application/json' \ --data '{ "amount_cents": 15000, "description": "Pedido 1234", "external_id": "pedido-1234", "expires_in": 1800, "payer": { "name": "Maria Silva", "document": "12345678909" }, "metadata": { "order_id": "1234" } }' ``` --- # Consultar o status da forma correta Use o webhook como fonte principal e a consulta por id como reforço, com intervalo mínimo. Veja cada status e o que fazer. ## Faça assim 1. Crie o pagamento e guarde o id junto com o pedido. 2. Espere o webhook. Quando chegar payment.paid, valide a assinatura e libere o pedido. 3. Como reforço, consulte GET /v1/payments/{id} enquanto o status for pending. Consulte no máximo uma vez a cada 30 segundos por pagamento. 4. Pare de consultar quando o status for final: paid, expired, failed, canceled ou refunded. > Atenção: nunca libere um pedido porque o cliente disse que pagou, ou porque a tela dele mostrou sucesso. Libere só com o status paid vindo do webhook validado ou da consulta pela API. ## Por que o webhook primeiro O webhook chega segundos depois do pagamento. A consulta repetida gasta o seu limite de requisições e atrasa a confirmação. Use a consulta só para cobrir um webhook perdido, por exemplo se o seu servidor estava fora do ar. ## Status do pagamento | Status | O que significa | O que fazer | | --- | --- | --- | | pending | Criado. Esperando o cliente pagar. | Mostre o Pix e espere. | | paid | Pago e confirmado. O valor entrou no seu saldo. | Libere o pedido. É final. | | expired | O prazo (expires_at) acabou sem pagamento. | Não mostre mais o Pix. Crie outro pagamento se o cliente ainda quiser pagar. | | failed | Não foi possível criar a cobrança Pix. | Crie outro pagamento com um novo external_id. | | canceled | A cobrança foi cancelada antes do pagamento. | Não libere. Crie outro pagamento se precisar. | | refunded | O valor foi devolvido ao cliente. | Desfaça a liberação do pedido. É final. | > Pagamento atrasado: se o cliente pagar depois de expires_at, o pagamento vira paid e o campo paid_late vem true. O valor entra no seu saldo. Decida no seu sistema se ainda libera o pedido ou se pede um reembolso (https://docs.redeutopia.com/reembolsos). ## Exemplo de fluxo completo 1. O cliente fecha o pedido 1234 no seu site. 2. Seu servidor calcula o total (R$ 150,00) e chama POST /v1/payments com amount_cents: 15000 e Idempotency-Key: pedido-1234. 3. Seu servidor guarda o id devolvido no pedido 1234 e mostra o pix.copy_paste ao cliente. 4. O cliente paga. Você recebe o webhook payment.paid, valida a assinatura, confere que o id é o do pedido 1234 e libera. 5. Se o webhook não chegar em alguns minutos, a consulta de reforço encontra paid e você libera do mesmo jeito. 6. Se nada acontecer até expires_at, o status vira expired e você encerra o pedido. ## Erros ao consultar Se a consulta falhar com 429 ou 5xx, espere e tente de novo, aumentando a espera a cada tentativa. Não aumente a frequência das consultas. --- # Buscar um pagamento Devolve o pagamento com o status atual. Use como reforço do webhook, com intervalo mínimo. Endpoint: GET https://api.redeutopia.com/v1/payments/{id} Escopo necessário: PAYMENT:READ Envie o id que a criação devolveu. A resposta tem o mesmo formato da criação, com o status atual. > Atenção: consulte no máximo uma vez a cada 30 segundos por pagamento, e só enquanto o status for pending. Veja Consultar o status da forma correta (https://docs.redeutopia.com/consultar-status). ## Resposta A API responde 200 com o pagamento. | Campo | Tipo | Descrição | | --- | --- | --- | | id | string | Id do pagamento. | | status | string | Status atual. Veja os status (https://docs.redeutopia.com/consultar-status#status-do-pagamento). | | amount_cents | integer | Valor cobrado, em centavos. | | fee_cents | integer | Taxa da plataforma, em centavos. | | net_cents | integer | Valor que entra no seu saldo. | | pix | object \| null | Dados do Pix. null quando o pagamento não pode mais ser pago. | | pix.copy_paste | string | Código Pix copia e cola. | | pix.qr_svg | string | QR Code do mesmo código, como imagem SVG. Vem quando pix vem. | | expires_at | string (ISO 8601) \| null | Até quando o Pix pode ser pago. | | paid_at | string (ISO 8601) \| null | Quando o pagamento foi confirmado. | | paid_late | boolean | true quando o pagamento chegou depois de expires_at. | | external_id | string \| null | O id do pedido que você enviou. | | description | string \| null | A descrição do Pix. | | customer | object \| null | Quem paga. | | customer.name | string | Nome de quem paga. | | customer.document | string | Documento de quem paga, mascarado. | | metadata | object | Os pares que você enviou. | | payment_url | string | Página pronta de pagamento. | | created_at | string (ISO 8601) | Quando o pagamento foi criado. | ## Erros | HTTP | Código | Quando acontece | O que fazer | | --- | --- | --- | --- | | 404 | not_found | Não existe pagamento com este id na sua conta. | Confira o id guardado no pedido. | | 429 | too_many_attempts | Muitas requisições com esta chave. | Espere e consulte com menos frequência. | Exemplo de resposta (200): ```json { "id": "0b5c1f7e-4a8d-4f2b-9c3e-6d7a8b9c0d1e", "status": "paid", "amount_cents": 15000, "fee_cents": 1050, "net_cents": 13950, "pix": null, "expires_at": "2026-11-22T15:30:00Z", "paid_at": "2026-11-22T15:04:12Z", "paid_late": false, "external_id": "pedido-1234", "description": "Pedido 1234", "customer": { "name": "Maria Silva", "document": "***.***.***-09" }, "metadata": { "order_id": "1234" }, "payment_url": "https://pay.redeutopia.com/pay/0b5c1f7e-4a8d-4f2b-9c3e-6d7a8b9c0d1e", "created_at": "2026-11-22T15:00:00Z" } ``` Exemplo com cURL: ```bash curl --request GET \ --url 'https://api.redeutopia.com/v1/payments/0b5c1f7e-4a8d-4f2b-9c3e-6d7a8b9c0d1e' \ --header "Authorization: Bearer $PAYMENTS_API_KEY" ``` --- # Listar pagamentos e paginação Lista os pagamentos da sua conta, do mais novo para o mais antigo, com filtros e paginação por cursor. Endpoint: GET https://api.redeutopia.com/v1/payments Escopo necessário: PAYMENT:READ Use a lista para conciliar pedidos ou encontrar um pagamento pelo external_id. ## Parâmetros | Parâmetro | Descrição | | --- | --- | | status | Filtra por status: pending, paid, expired, failed, canceled ou refunded. | | external_id | Filtra pelo id do pedido no seu sistema. | | q | Busca pelo início do id do pagamento, por parte do external_id ou do nome do cliente (até 60 caracteres). | | period | Só os pagamentos criados no período: today, 30d, 90d, month, year ou custom. Sem ele, a lista não tem limite de data. | | from | Com period=custom: primeiro dia, no formato AAAA-MM-DD. | | to | Com period=custom: último dia (incluído), no formato AAAA-MM-DD. | | limit | Quantos itens por página, de 1 a 100. Padrão: 20. | | cursor | O next_cursor da página anterior. | Qualquer outro parâmetro é recusado com 400 e o código invalid_request. ## Paginação 1. Chame sem cursor para receber a primeira página. 2. Se a resposta tiver next_cursor, chame de novo com cursor igual a esse valor. 3. Quando a resposta vier sem next_cursor, você chegou ao fim. O cursor é estável: pagamentos novos não fazem itens se repetirem ou sumirem entre as páginas. ## Resposta | Campo | Tipo | Descrição | | --- | --- | --- | | data | array | Os pagamentos desta página, no mesmo formato de Buscar um pagamento (https://docs.redeutopia.com/buscar-pagamento), sem pix.qr_svg. | | next_cursor | string | Cursor da próxima página. Não vem na última página. | ## Erros | HTTP | Código | Quando acontece | O que fazer | | --- | --- | --- | --- | | 400 | invalid_request | Parâmetro desconhecido, status, período ou cursor inválido. | Confira os parâmetros desta página. | | 429 | too_many_attempts | Muitas requisições com esta chave. | Espere e tente de novo. | Exemplo de resposta (200): ```json { "data": [ { "id": "0b5c1f7e-4a8d-4f2b-9c3e-6d7a8b9c0d1e", "status": "paid", "amount_cents": 15000, "fee_cents": 1050, "net_cents": 13950, "pix": null, "expires_at": "2026-11-22T15:30:00Z", "paid_at": "2026-11-22T15:04:12Z", "paid_late": false, "external_id": "pedido-1234", "description": "Pedido 1234", "customer": { "name": "Maria Silva", "document": "***.***.***-09" }, "metadata": { "order_id": "1234" }, "payment_url": "https://pay.redeutopia.com/pay/0b5c1f7e-4a8d-4f2b-9c3e-6d7a8b9c0d1e", "created_at": "2026-11-22T15:00:00Z" } ], "next_cursor": "MTc2Mzc1MzYwMDAwMDAwMDAwMHwwYjVj" } ``` Exemplo com cURL: ```bash curl --request GET \ --url 'https://api.redeutopia.com/v1/payments?status=paid&limit=20' \ --header "Authorization: Bearer $PAYMENTS_API_KEY" ``` --- # Reembolsos Devolva ao cliente o valor de um pagamento, inteiro ou em parte. Todo pedido de reembolso passa por aprovação. ## Como funciona 1. Você pede o reembolso de um pagamento com status paid, pelo painel ou pela API. 2. O valor sai do seu saldo disponível e fica reservado. 3. Nossa equipe analisa o pedido. 4. Aprovado, devolvemos o valor por Pix para o CPF ou CNPJ de quem pagou, conforme confirmado pelo banco. Se quem pagou não for a pessoa informada na cobrança, o reembolso não é enviado automaticamente: nossa equipe confere e devolve a quem pagou, ou recusa o pedido. 5. Você recebe os eventos refund.approved e depois refund.completed. Pela API, use Pedir um reembolso (https://docs.redeutopia.com/pedir-reembolso) e acompanhe com Buscar um reembolso (https://docs.redeutopia.com/buscar-reembolso). Você pode pedir o valor inteiro ou só uma parte. A soma dos seus reembolsos nunca passa do valor pago. Quando o pagamento é devolvido por inteiro, ele muda para refunded. Enquanto houver uma infração (https://docs.redeutopia.com/infracoes) em aberto no pagamento, não é possível pedir reembolso e nenhum reembolso dele é enviado. Se a infração terminar com o valor devolvido ao cliente, esse valor sai do seu saldo, mesmo que você já tenha feito um reembolso. ## Status do reembolso | Status | O que significa | O que fazer | | --- | --- | --- | | requested | Pedido recebido. O valor está reservado no seu saldo. | Espere a análise. | | approved | Aprovado. A devolução está sendo enviada. | Espere a conclusão. | | completed | O valor foi devolvido ao cliente. | Atualize o pedido no seu sistema. É final. | | rejected | Recusado. O motivo vem em decision_reason. O valor voltou ao seu saldo. | Leia o motivo. É final. | | failed | O envio falhou. O valor voltou ao seu saldo. | Peça de novo ou fale com o suporte. É final. | ## Motivos aceitos | Motivo | Quando usar | | --- | --- | | customer_request | O cliente pediu o dinheiro de volta. | | duplicate | O cliente pagou duas vezes. | | fraud | Você suspeita de fraude. | | other | Outro motivo. Explique na descrição. | ## Taxa A taxa da plataforma do pagamento original não é devolvida, a menos que a sua conta tenha outra condição combinada. > Atenção: peça reembolsos sempre do seu servidor, com Idempotency-Key. Assim um clique duplo ou uma repetição nunca cria dois pedidos. --- # Infrações Quando um cliente contesta um Pix no banco dele, o valor contestado fica retido até a análise terminar. ## Como funciona 1. O cliente contesta o pagamento no banco dele (por exemplo, por fraude ou por não receber o produto). 2. Nós recebemos a contestação e abrimos uma infração ligada ao pagamento. 3. O valor contestado fica retido no seu saldo. 4. Você recebe o evento infraction.opened. 5. Quando a análise termina, você recebe infraction.updated com o resultado. ## Status da infração | Status | O que significa | | --- | --- | | open | Em análise. O valor está retido. | | in_review | Em análise final. O valor continua retido. | | closed_merchant | Resolvida a seu favor. O valor volta para o seu saldo disponível. | | closed_payer | Resolvida a favor de quem pagou. O valor foi devolvido ao cliente. | ## O que fazer - Acompanhe as infrações no painel, em Financeiro > Reembolsos e infrações, ou pela API em Listar infrações e reembolsos (https://docs.redeutopia.com/listar-infracoes). - Guarde comprovantes de entrega e de atendimento de cada pedido. Eles ajudam na análise. - Fale com o suporte se tiver informações sobre a contestação. --- # Saldo e saques Veja quanto você tem disponível e saque para a sua chave Pix. Todo saque passa por aprovação. ## Saldo O saldo disponível é o que você pode sacar ou usar em reembolsos. Consulte pela API em Consultar o saldo (https://docs.redeutopia.com/consultar-saldo). Cada pagamento confirmado soma o net_cents (valor menos a taxa). Saques e reembolsos pedidos ficam reservados até a conclusão. Valores de infrações abertas ficam retidos. ## Chave Pix de saque 1. Cadastre uma chave Pix no painel, em Financeiro > Saques. Tipos aceitos: CPF, CNPJ, e-mail, celular ou chave aleatória. 2. A primeira chave cadastrada no painel vale na hora. Pela API, toda chave passa por análise, inclusive a primeira. 3. Para trocar a chave, cadastre a nova. Ela passa por análise. Até a aprovação, a chave antiga continua valendo. ## Como sacar 1. Peça o saque de um valor até o seu saldo disponível, no painel ou pela API em Pedir um saque (https://docs.redeutopia.com/pedir-saque). 2. O valor fica reservado e o saque entra em análise. 3. Aprovado, enviamos o Pix para a sua chave. 4. Você recebe o evento withdrawal.paid. Existem valores mínimo e máximo por saque e um limite por dia. Se houver taxa de saque, ela aparece em fee_cents e sai do saldo junto com o saque. ## Status do saque | Status | O que significa | | --- | --- | | requested | Pedido recebido. O valor está reservado. | | approved | Aprovado. O Pix está sendo enviado. | | paid | Pago na sua chave Pix. É final. | | rejected | Recusado. O motivo vem em reason. O valor voltou ao saldo. É final. | | failed | O envio falhou. O valor voltou ao saldo. Peça de novo. É final. | --- # Webhooks Receba avisos no seu servidor quando um pagamento, reembolso, saque ou infração muda. Valide a assinatura de cada aviso. ## Como funciona 1. Cadastre a URL HTTPS do seu servidor no painel, em Integração > Webhooks. 2. Guarde o segredo de assinatura (começa com whsec_). Ele aparece uma única vez. 3. A cada mudança, enviamos um POST com o evento em JSON para a sua URL. 4. Seu servidor valida a assinatura, guarda o evento e responde 2xx em até 10 segundos. ## Eventos | Evento | Quando acontece | | --- | --- | | payment.paid | O pagamento foi confirmado. Libere o pedido. | | payment.expired | O prazo do Pix acabou sem pagamento. | | payment.failed | Não foi possível criar a cobrança Pix. | | refund.requested | Você pediu um reembolso. | | refund.approved | O reembolso foi aprovado e vai ser pago. | | refund.completed | O valor foi devolvido ao cliente. | | refund.rejected | O reembolso foi recusado. O motivo vem em decision_reason. | | refund.failed | O envio do reembolso falhou. O valor voltou ao seu saldo. | | withdrawal.requested | Você pediu um saque. | | withdrawal.approved | O saque foi aprovado e vai ser pago. | | withdrawal.paid | O saque foi pago na sua conta. | | withdrawal.rejected | O saque foi recusado. O motivo vem em reason. | | withdrawal.failed | O envio do saque falhou. O valor voltou ao seu saldo. | | infraction.opened | Um cliente abriu uma contestação. O valor ficou retido. | | infraction.updated | A contestação mudou de status. | ## Formato Todo evento tem o mesmo formato. Em data vem o objeto no momento da mudança. created_at é o momento da mudança, em UTC, no formato RFC 3339. JSON: ```json { "id": "7d9e6c52-3f1a-4b8e-9a0d-2c4f6e8a1b3c", "type": "payment.paid", "created_at": "2026-11-22T15:04:13.284512Z", "data": { "id": "0b5c1f7e-4a8d-4f2b-9c3e-6d7a8b9c0d1e", "status": "paid", "amount_cents": 15000, "fee_cents": 1050, "net_cents": 13950, "external_id": "pedido-1234", "metadata": { "order_id": "1234" }, "paid_at": "2026-11-22T15:04:12Z", "paid_late": false, "expires_at": "2026-11-22T15:30:00Z", "created_at": "2026-11-22T15:00:00Z" } } ``` Cabeçalhos de cada envio: | Cabeçalho | O que é | | --- | --- | | Webhook-Id | O id do evento. É o mesmo em todos os reenvios. | | Webhook-Timestamp | Horário deste envio, em segundos Unix. | | Webhook-Signature | A assinatura: v1= seguido de 64 caracteres hexadecimais. | | Content-Type | application/json | ## Como validar a assinatura 1. Leia o corpo cru da requisição, antes de qualquer conversão de JSON. 2. Monte o texto Webhook-Id + . + Webhook-Timestamp + . + corpo cru. 3. Calcule o HMAC-SHA256 desse texto. A chave é o segredo inteiro, com o prefixo whsec_. 4. Escreva o resultado em hexadecimal minúsculo e coloque v1= na frente. 5. Compare com Webhook-Signature usando comparação de tempo constante. 6. Recuse se o Webhook-Timestamp estiver a mais de 5 minutos do seu relógio. Se qualquer passo falhar, responda 400 e não use o conteúdo. Node.js: ```javascript import crypto from 'node:crypto'; import express from 'express'; const app = express(); const SECRET = process.env.PAYMENTS_WEBHOOK_SECRET; // whsec_... app.post('/webhooks/pagamentos', express.raw({ type: 'application/json' }), (req, res) => { const id = req.get('Webhook-Id') ?? ''; const timestamp = req.get('Webhook-Timestamp') ?? ''; const signature = req.get('Webhook-Signature') ?? ''; if (!id || !/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) { return res.sendStatus(400); } const expected = 'v1=' + crypto.createHmac('sha256', SECRET) .update(`${id}.${timestamp}.`).update(req.body).digest('hex'); const a = Buffer.from(signature); const b = Buffer.from(expected); if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.sendStatus(400); const event = JSON.parse(req.body); // Guarde o evento numa fila e processe depois. Ignore se event.id já foi processado. res.sendStatus(200); }); ``` PHP: ```php 300) { http_response_code(400); exit; } $expected = 'v1=' . hash_hmac('sha256', $id . '.' . $timestamp . '.' . $body, $secret); if (!hash_equals($expected, $signature)) { http_response_code(400); exit; } $event = json_decode($body, true); // Guarde o evento numa fila e processe depois. Ignore se $event['id'] já foi processado. http_response_code(200); ``` Python: ```python import hashlib import hmac import os import time from flask import Flask, abort, request app = Flask(__name__) SECRET = os.environ["PAYMENTS_WEBHOOK_SECRET"].encode() # whsec_... @app.post("/webhooks/pagamentos") def webhook(): event_id = request.headers.get("Webhook-Id", "") timestamp = request.headers.get("Webhook-Timestamp", "") signature = request.headers.get("Webhook-Signature", "") if not event_id or not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300: abort(400) signed = f"{event_id}.{timestamp}.".encode() + request.get_data() expected = "v1=" + hmac.new(SECRET, signed, hashlib.sha256).hexdigest() if not hmac.compare_digest(expected, signature): abort(400) event = request.get_json() # Guarde o evento numa fila e processe depois. Ignore se event["id"] já foi processado. return "", 200 ``` Shell: ```shell # Confira uma assinatura na linha de comando (útil em testes). printf '%s.%s.%s' "$WEBHOOK_ID" "$WEBHOOK_TIMESTAMP" "$BODY" \ | openssl dgst -sha256 -hmac "$PAYMENTS_WEBHOOK_SECRET" -hex ``` ## Reenvios - Um envio dá certo quando o seu servidor responde 2xx em até 10 segundos. Redirecionamentos contam como falha. - Se falhar, reenviamos o mesmo evento, com o mesmo id. A espera dobra a cada tentativa: 30 segundos, 1 minuto, 2 minutos, e assim por diante, até 6 horas entre tentativas. - São até 12 tentativas, por cerca de 26 horas. Depois disso o evento fica marcado como não entregue no painel. - Os eventos podem chegar fora de ordem. Use o status de data e o horário created_at. ## Idempotência por event.id O mesmo evento pode chegar mais de uma vez. Guarde o id de cada evento processado e ignore os repetidos. Faça isso na mesma transação em que você atualiza o pedido. ## Boas práticas - Responda 2xx rápido e processe numa fila. Não faça chamadas lentas antes de responder. - Antes de liberar um pedido ou mexer em dinheiro, confira o pagamento com Buscar um pagamento (https://docs.redeutopia.com/buscar-pagamento). - Guarde o segredo numa variável de ambiente, como a chave de API. --- # Idempotência Envie o cabeçalho Idempotency-Key em todo POST. Assim uma requisição repetida nunca cria um segundo pagamento. ## Por que usar A rede falha. Se a resposta de um POST se perder, você não sabe se o pagamento foi criado. Com a Idempotency-Key, você repete a mesma requisição sem medo: a API devolve o resultado da primeira vez e não cria nada novo. ## Faça assim 1. Gere a chave a partir do seu pedido, por exemplo pedido-1234. Ela precisa ter de 8 a 200 caracteres. 2. Envie a chave no cabeçalho Idempotency-Key de todo POST. 3. Ao repetir por falha de rede, envie a mesma chave e o mesmo corpo. 4. Para um pedido novo, use uma chave nova. Texto: ```text Idempotency-Key: pedido-1234 ``` ## O que a API responde | Situação | Resposta | | --- | --- | | Chave nova | A API executa e guarda o resultado. | | Mesma chave e mesmo corpo | A API devolve o resultado guardado. Nada novo é criado. | | Mesma chave e corpo diferente | 422 com o código idempotency_key_reused. | | Mesma chave ainda em andamento | 409 com o código idempotency_in_progress. Espere e repita. | | Sem a chave | 400 com o código idempotency_key_required. | A API guarda a chave por 24 horas. A resposta repetida é a da criação: para ver o status atual, use Buscar um pagamento (https://docs.redeutopia.com/buscar-pagamento). > Atenção: não gere uma chave aleatória a cada tentativa. Uma chave nova em cada tentativa desliga a proteção e pode criar cobranças duplicadas. --- # Erros e códigos Toda resposta de erro tem um código estável em inglês e uma mensagem em português. Trate os erros pelo código. ## Formato JSON: ```json { "code": "validation_failed", "message": "Alguns campos precisam de atenção.", "fields": { "payer.document": "invalid_document" } } ``` - code: código estável. Use no seu código para decidir o que fazer. - message: frase em português para mostrar ou registrar. Pode mudar de texto. - fields: só em validation_failed. Diz qual campo está errado e por quê. - support_code: só em erros inesperados. Envie ao suporte. ## Status HTTP | HTTP | O que significa | Pode repetir? | | --- | --- | --- | | 400 | Requisição malformada ou cabeçalho faltando. | Não. Corrija antes. | | 401 | Chave ausente, errada ou revogada. | Não. Confira a chave. | | 403 | A chave não tem o escopo, ou a origem foi recusada. | Não. | | 404 | O recurso não existe na sua conta. | Não. | | 409 | Conflito: external_id repetido ou chave de idempotência em andamento. | Só idempotency_in_progress, com a mesma chave. | | 413 | Corpo grande demais. | Não. | | 422 | Campos inválidos ou chave de idempotência reutilizada. | Não. Corrija antes. | | 429 | Limite de requisições atingido. | Sim, depois de esperar. | | 5xx | Falha temporária do nosso lado. | Sim, com a mesma Idempotency-Key. | ## Como repetir Repita só 429, 5xx e falhas de rede. Espere mais a cada tentativa (por exemplo 1, 2, 4, 8 segundos) e pare depois de algumas tentativas. Em POST, repita sempre com a mesma Idempotency-Key. ## Erros de campo | Código | Mensagem | | --- | --- | | required | Campo obrigatório. | | invalid | Valor inválido. | | invalid_document | Informe um CPF ou CNPJ válido. | | amount_out_of_range | Valor fora dos limites permitidos. | ## Todos os códigos | Código | Mensagem | | --- | --- | | invalid_request | Requisição inválida. | | invalid_period | Período inválido. Escolha datas até hoje, com no máximo 24 meses. | | unknown_field | A requisição contém campos não permitidos. | | unsupported_media_type | Formato da requisição não suportado. | | body_too_large | A requisição é grande demais. | | validation_failed | Alguns campos precisam de atenção. | | unauthenticated | Faça login para continuar. | | too_many_attempts | Muitas tentativas. Aguarde alguns minutos e tente novamente. | | origin_forbidden | Origem da requisição não permitida. | | forbidden | Você não tem permissão para esta ação. | | not_found | Não encontrado. | | insufficient_scope | Esta chave de API não tem permissão para esta operação. | | payments_unavailable | Pagamentos Pix estão temporariamente indisponíveis. Tente novamente em alguns minutos. | | duplicate_external_id | Já existe um pagamento com este external_id. | | invalid_transition | Esta ação não é permitida no status atual. | | insufficient_balance | Saldo disponível insuficiente para esta operação. | | payment_not_refundable | Este pagamento não pode ser reembolsado: ele não foi pago ou já foi reembolsado por completo. | | payout_key_required | Cadastre uma chave Pix de saque antes de solicitar um saque. | | payout_key_pending | Já existe uma troca de chave Pix aguardando análise. | | payout_key_conflict | Outra alteração da chave Pix de saque foi feita ao mesmo tempo. Consulte suas chaves e tente de novo. | | infraction_open | Este pagamento tem uma contestação em aberto. O reembolso só pode seguir depois que ela for resolvida. | | daily_limit_exceeded | O limite diário de saques foi atingido. Tente novamente amanhã. | | reauth_failed | Senha incorreta. Confira e tente de novo. | | reauth_required | Por segurança, confirme sua senha para continuar. | | delivery_not_dead | Só é possível reenviar entregas que falharam em todas as tentativas. | | idempotency_key_required | Cabeçalho Idempotency-Key obrigatório. | | idempotency_key_reused | Esta Idempotency-Key já foi usada com outro conteúdo. | | idempotency_in_progress | Uma requisição com esta Idempotency-Key ainda está em andamento. | | method_not_allowed | Método não permitido. | | internal_error | Erro interno. Tente novamente em instantes. | | step_up_required | Confirme o código do autenticador para continuar. | | stale_version | Outra pessoa alterou estes dados agora mesmo. Recarregue a página e tente de novo. | | webhook_token_unavailable | O endereço completo deste webhook não pode ser exibido. Gere um novo token para obter um endereço. | --- # Limites Limites de requisições por chave, tamanhos e valores aceitos pela API. ## Requisições | Limite | Valor | | --- | --- | | Requisições por chave de API | 300 por minuto | | Tentativas com chave inválida, por endereço IP | 30 por minuto | | Consulta de status do mesmo pagamento | No máximo 1 a cada 30 segundos | Acima do limite, a API responde 429 com o código too_many_attempts. Espere um minuto e reduza a frequência. ## Tamanhos | Limite | Valor | | --- | --- | | Corpo da requisição | 64 KB | | Itens por página nas listas | 1 a 100 (padrão 20) | | description | 140 caracteres | | external_id | 120 caracteres, sem espaços | | metadata | 20 chaves; chave com até 40 caracteres (letras, números, _, ., -); valor com até 500 caracteres | | Idempotency-Key | 8 a 200 caracteres | ## Valores | Limite | Valor | | --- | --- | | Valor mínimo de um pagamento | R$ 1,00 (amount_cents: 100) | | Valor máximo de um pagamento | O limite da sua conta. Acima dele: amount_out_of_range. | | Validade do Pix | 1 minuto a 7 dias (padrão 30 minutos) | | Produtos em items | 1 a 50 por pagamento; qty de 1 a 1000 | --- # Boas práticas de segurança As regras que protegem o seu dinheiro e os dados dos seus clientes. Siga todas. ## A chave fica só no servidor - Guarde a chave numa variável de ambiente ou num cofre de segredos. - Nunca coloque a chave no navegador, no aplicativo, no repositório de código, em prints ou em logs. - Dê a cada chave só os escopos que ela precisa. - Se a chave vazar, revogue no painel na hora e crie outra. ## Nunca confie no navegador - Calcule o valor no servidor, a partir do pedido. Ignore preços, totais e descontos que vêm do navegador. - O navegador nunca chama a API. Ele fala só com o seu servidor. - Libere o pedido só com o status paid vindo do webhook validado ou da consulta pela API. Nunca porque a tela do cliente mostrou sucesso. ## Valide todo webhook - Confira a assinatura de cada webhook antes de usar o conteúdo. Recuse se a assinatura não bater ou se o horário estiver velho. - Ignore eventos repetidos pelo id do evento. - Confira que o pagamento do evento é o do seu pedido (pelo id guardado ou pelo external_id). - Veja Webhooks (https://docs.redeutopia.com/webhooks). ## Guarde o id do pagamento Guarde o id devolvido pela API junto com o pedido. Use esse id para consultar o status e para ligar cada webhook ao pedido certo. ## Use HTTPS e repita com cuidado - Seu endereço de webhook precisa ser HTTPS. - Em todo POST, envie a Idempotency-Key. Ao repetir, use a mesma chave. - Repita só erros temporários, com espera crescente. ## Proteja os dados do cliente Envie só os dados que a API pede. Não registre CPF ou CNPJ completo nos seus logs. --- # Perguntas frequentes Respostas curtas para as dúvidas mais comuns. ## Existe ambiente de teste? Não. Toda conta aprovada está em produção. Para testar, crie um pagamento de R$ 1,00 e pague com o seu próprio banco. Se quiser o dinheiro de volta, peça um reembolso (https://docs.redeutopia.com/reembolsos). ## Quanto tempo o cliente tem para pagar? 30 minutos, se você não enviar expires_in. Você pode escolher de 1 minuto a 7 dias. ## O cliente pagou depois do prazo. E agora? O pagamento vira paid com paid_late: true e o valor entra no seu saldo. Decida se libera o pedido ou se devolve o valor com um reembolso. ## O `pix` veio `null` na criação. O que faço? O código ainda está sendo gerado. Ele chega no webhook ou na consulta pelo id em poucos segundos. ## Posso chamar a API direto do navegador ou do aplicativo? Não. A chave ficaria exposta. O navegador e o aplicativo falam com o seu servidor, e o seu servidor fala com a API. ## Como sei qual pedido foi pago? Guarde o id do pagamento no pedido. Envie também o external_id com o id do pedido. Os dois voltam no webhook. ## Perdi a chave de API. Consigo ver de novo? Não. A chave aparece uma única vez. Revogue a antiga no painel e crie outra. ## Quanto tempo leva para o dinheiro entrar no saldo? O valor entra no saldo assim que o pagamento é confirmado (status paid). --- # Pedir um reembolso Pede a devolução de um pagamento pago, inteira ou parcial. O valor fica reservado no seu saldo até a análise. Endpoint: POST https://api.redeutopia.com/v1/payments/{id}/refunds Escopo necessário: REFUND:CREATE Cabeçalho obrigatório: Idempotency-Key Envie o id do pagamento no caminho. Sem amount_cents, devolvemos todo o valor que ainda pode ser devolvido. Veja como funciona em Reembolsos (https://docs.redeutopia.com/reembolsos). ## Requisição Cabeçalhos: Authorization, Content-Type: application/json e Idempotency-Key (obrigatório). | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | amount_cents | integer | não | Valor a devolver, em centavos. Sem ele (ou com 0), devolvemos tudo o que ainda pode ser devolvido. | | reason | string | sim | Motivo: customer_request, duplicate, fraud ou other. | | description | string | não | Explicação, até 500 caracteres. Use quando o motivo for other. | ## Resposta A API responde 201 com o reembolso em requested. | Campo | Tipo | Descrição | | --- | --- | --- | | id | string | Id do reembolso. | | payment_id | string | Id do pagamento devolvido. | | status | string | Status do reembolso. Veja os status (https://docs.redeutopia.com/reembolsos#status-do-reembolso). | | amount_cents | integer | Valor devolvido, em centavos. | | reason | string | O motivo enviado. | | description | string \| null | A explicação enviada. | | decision_reason | string \| null | Por que o reembolso foi recusado. null nos outros casos. | | fee_returned_cents | integer \| null | Quanto da taxa voltou ao seu saldo, quando o reembolso termina. | | created_at | string (ISO 8601) | Quando o reembolso foi pedido. | | completed_at | string (ISO 8601) \| null | Quando o valor foi devolvido ao cliente. | ## Erros | HTTP | Código | Quando acontece | O que fazer | | --- | --- | --- | --- | | 404 | not_found | Não existe pagamento com este id na sua conta. | Confira o id. | | 409 | payment_not_refundable | O pagamento não está pago ou já foi devolvido por inteiro. | Confira o status do pagamento. | | 409 | insufficient_balance | Seu saldo disponível não cobre o reembolso. | Espere novos pagamentos entrarem no saldo. | | 409 | infraction_open | O pagamento tem uma infração em aberto. | Espere a infração ser resolvida. | | 422 | validation_failed | Campo inválido, ou valor maior do que o que ainda pode ser devolvido. | Veja o campo fields. | Exemplo de corpo da requisição: ```json { "amount_cents": 5000, "reason": "customer_request", "description": "Cliente desistiu de um item" } ``` Exemplo de resposta (201): ```json { "id": "5f2a9c1e-7b3d-4e8a-9c0b-1d2e3f4a5b6c", "payment_id": "0b5c1f7e-4a8d-4f2b-9c3e-6d7a8b9c0d1e", "status": "requested", "amount_cents": 5000, "reason": "customer_request", "description": "Cliente desistiu de um item", "decision_reason": null, "fee_returned_cents": null, "created_at": "2026-11-23T10:00:00Z", "completed_at": null } ``` Exemplo com cURL: ```bash curl --request POST \ --url 'https://api.redeutopia.com/v1/payments/0b5c1f7e-4a8d-4f2b-9c3e-6d7a8b9c0d1e/refunds' \ --header "Authorization: Bearer $PAYMENTS_API_KEY" \ --header 'Idempotency-Key: pedido-1234' \ --header 'Content-Type: application/json' \ --data '{ "amount_cents": 5000, "reason": "customer_request", "description": "Cliente desistiu de um item" }' ``` --- # Listar reembolsos Lista os seus reembolsos, do mais novo para o mais antigo, com filtros e paginação por cursor. Endpoint: GET https://api.redeutopia.com/v1/refunds Escopo necessário: REFUND:READ ## Parâmetros | Parâmetro | Descrição | | --- | --- | | status | Filtra por status: requested, approved, completed, rejected ou failed. | | payment_id | Só os reembolsos de um pagamento. | | limit | Quantos itens por página, de 1 a 100. Padrão: 20. | | cursor | O next_cursor da página anterior. Veja Paginação (https://docs.redeutopia.com/listar-pagamentos#paginacao). | ## Resposta | Campo | Tipo | Descrição | | --- | --- | --- | | data | array | Os reembolsos desta página, no mesmo formato de Buscar um reembolso (https://docs.redeutopia.com/buscar-reembolso). | | next_cursor | string | Cursor da próxima página. Não vem na última página. | ## Erros | HTTP | Código | Quando acontece | O que fazer | | --- | --- | --- | --- | | 400 | invalid_request | Parâmetro desconhecido ou inválido. | Confira os parâmetros desta página. | Exemplo de resposta (200): ```json { "data": [ { "id": "5f2a9c1e-7b3d-4e8a-9c0b-1d2e3f4a5b6c", "payment_id": "0b5c1f7e-4a8d-4f2b-9c3e-6d7a8b9c0d1e", "status": "completed", "amount_cents": 5000, "reason": "customer_request", "description": "Cliente desistiu de um item", "decision_reason": null, "fee_returned_cents": 0, "created_at": "2026-11-23T10:00:00Z", "completed_at": "2026-11-23T14:20:00Z" } ] } ``` Exemplo com cURL: ```bash curl --request GET \ --url 'https://api.redeutopia.com/v1/refunds?status=completed&limit=20' \ --header "Authorization: Bearer $PAYMENTS_API_KEY" ``` --- # Buscar um reembolso Devolve um reembolso com o status atual. Endpoint: GET https://api.redeutopia.com/v1/refunds/{id} Escopo necessário: REFUND:READ Prefira o webhook: os eventos refund.* avisam cada mudança. Use esta consulta como reforço. ## Resposta | Campo | Tipo | Descrição | | --- | --- | --- | | id | string | Id do reembolso. | | payment_id | string | Id do pagamento devolvido. | | status | string | Status do reembolso. Veja os status (https://docs.redeutopia.com/reembolsos#status-do-reembolso). | | amount_cents | integer | Valor devolvido, em centavos. | | reason | string | O motivo do pedido. | | description | string \| null | A explicação do pedido. | | decision_reason | string \| null | Por que o reembolso foi recusado. null nos outros casos. | | fee_returned_cents | integer \| null | Quanto da taxa voltou ao seu saldo, quando o reembolso termina. | | created_at | string (ISO 8601) | Quando o reembolso foi pedido. | | completed_at | string (ISO 8601) \| null | Quando o valor foi devolvido ao cliente. | ## Erros | HTTP | Código | Quando acontece | O que fazer | | --- | --- | --- | --- | | 404 | not_found | Não existe reembolso com este id na sua conta. | Confira o id. | Exemplo de resposta (200): ```json { "id": "5f2a9c1e-7b3d-4e8a-9c0b-1d2e3f4a5b6c", "payment_id": "0b5c1f7e-4a8d-4f2b-9c3e-6d7a8b9c0d1e", "status": "completed", "amount_cents": 5000, "reason": "customer_request", "description": "Cliente desistiu de um item", "decision_reason": null, "fee_returned_cents": 0, "created_at": "2026-11-23T10:00:00Z", "completed_at": "2026-11-23T14:20:00Z" } ``` Exemplo com cURL: ```bash curl --request GET \ --url 'https://api.redeutopia.com/v1/refunds/0b5c1f7e-4a8d-4f2b-9c3e-6d7a8b9c0d1e' \ --header "Authorization: Bearer $PAYMENTS_API_KEY" ``` --- # Consultar o saldo Devolve o seu saldo disponível, o valor reservado para pedidos em andamento e o valor retido por infrações. Endpoint: GET https://api.redeutopia.com/v1/balance Escopo necessário: BALANCE:READ ## Resposta | Campo | Tipo | Descrição | | --- | --- | --- | | available_cents | integer | Disponível para saques e reembolsos, em centavos. | | processing_cents | integer | Reservado para saques e reembolsos em andamento. | | blocked_cents | integer | Retido por infrações abertas. | Exemplo de resposta (200): ```json { "available_cents": 1250000, "processing_cents": 50000, "blocked_cents": 0 } ``` Exemplo com cURL: ```bash curl --request GET \ --url 'https://api.redeutopia.com/v1/balance' \ --header "Authorization: Bearer $PAYMENTS_API_KEY" ``` --- # Cadastrar a chave Pix de saque Cadastra a chave Pix que recebe os seus saques. Pela API, toda chave passa por análise antes de valer. Endpoint: POST https://api.redeutopia.com/v1/payout-keys Escopo necessário: WITHDRAWAL:CREATE Cabeçalho obrigatório: Idempotency-Key Você tem uma chave de saque ativa por vez. Toda chave cadastrada pela API fica em pending_review até a aprovação, inclusive a primeira: assim uma chave de API vazada não consegue mudar o destino dos seus saques. Ao trocar de chave, a chave atual continua valendo até a nova ser aprovada. ## Requisição Cabeçalhos: Authorization, Content-Type: application/json e Idempotency-Key (obrigatório). | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | type | string | sim | Tipo da chave: cpf, cnpj, email, phone (celular com DDD) ou evp (chave aleatória). | | key | string | sim | A chave Pix. | ## Resposta A API responde 201 com a chave. | Campo | Tipo | Descrição | | --- | --- | --- | | id | string | Id da chave. | | type | string | Tipo da chave. | | key | string | A chave, mascarada. | | status | string | active (vale para saques) ou pending_review (em análise). | | created_at | string (ISO 8601) | Quando a chave foi cadastrada. | ## Erros | HTTP | Código | Quando acontece | O que fazer | | --- | --- | --- | --- | | 409 | payout_key_pending | Já existe uma troca de chave em análise. | Espere a análise terminar. | | 409 | payout_key_conflict | Outra chave foi cadastrada ao mesmo tempo. | Consulte suas chaves e tente de novo. | | 422 | validation_failed | A chave não é válida para o tipo informado. | Veja o campo fields. | Exemplo de corpo da requisição: ```json { "type": "cnpj", "key": "12345678000195" } ``` Exemplo de resposta (201): ```json { "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "type": "cnpj", "key": "**.***.***/****-95", "status": "pending_review", "created_at": "2026-11-23T09:00:00Z" } ``` Exemplo com cURL: ```bash curl --request POST \ --url 'https://api.redeutopia.com/v1/payout-keys' \ --header "Authorization: Bearer $PAYMENTS_API_KEY" \ --header 'Idempotency-Key: pedido-1234' \ --header 'Content-Type: application/json' \ --data '{ "type": "cnpj", "key": "12345678000195" }' ``` --- # Listar as chaves Pix de saque Mostra a chave de saque ativa e, se houver, a troca em análise. Endpoint: GET https://api.redeutopia.com/v1/payout-keys Escopo necessário: WITHDRAWAL:READ ## Resposta | Campo | Tipo | Descrição | | --- | --- | --- | | data | array | As chaves, no mesmo formato de Cadastrar a chave Pix de saque (https://docs.redeutopia.com/cadastrar-chave-pix). | | next_cursor | string | Não vem: a lista tem no máximo duas chaves. | Exemplo de resposta (200): ```json { "data": [ { "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "type": "cnpj", "key": "**.***.***/****-95", "status": "active", "created_at": "2026-11-23T09:00:00Z" } ] } ``` Exemplo com cURL: ```bash curl --request GET \ --url 'https://api.redeutopia.com/v1/payout-keys' \ --header "Authorization: Bearer $PAYMENTS_API_KEY" ``` --- # Pedir um saque Pede um saque do saldo disponível para a sua chave Pix ativa. O valor fica reservado até a análise. Endpoint: POST https://api.redeutopia.com/v1/withdrawals Escopo necessário: WITHDRAWAL:CREATE Cabeçalho obrigatório: Idempotency-Key O saque vai para a sua chave Pix ativa. Cadastre a chave antes em Cadastrar a chave Pix de saque (https://docs.redeutopia.com/cadastrar-chave-pix). Veja como funciona em Saldo e saques (https://docs.redeutopia.com/saldo-e-saques). ## Requisição Cabeçalhos: Authorization, Content-Type: application/json e Idempotency-Key (obrigatório). | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | amount_cents | integer | sim | Valor do saque, em centavos. Precisa estar entre o mínimo e o máximo por saque da sua conta. | ## Resposta A API responde 201 com o saque em requested. | Campo | Tipo | Descrição | | --- | --- | --- | | id | string | Id do saque. | | status | string | Status do saque. Veja os status (https://docs.redeutopia.com/saldo-e-saques#status-do-saque). | | amount_cents | integer | Valor do saque, em centavos. | | fee_cents | integer | Taxa do saque, em centavos. Sai do saldo junto com o saque. | | reason | string \| null | Por que o saque foi recusado. null nos outros casos. | | payout_key | string | A chave Pix que recebe o saque, mascarada. | | created_at | string (ISO 8601) | Quando o saque foi pedido. | | paid_at | string (ISO 8601) \| null | Quando o saque foi pago. | ## Erros | HTTP | Código | Quando acontece | O que fazer | | --- | --- | --- | --- | | 409 | payout_key_required | Você ainda não tem chave Pix de saque ativa. | Cadastre a chave. | | 409 | daily_limit_exceeded | O saque passa do limite do dia. | Peça um valor menor ou espere o próximo dia. | | 409 | insufficient_balance | O saldo disponível não cobre o saque e a taxa. | Consulte o saldo. | | 422 | validation_failed | Valor fora do mínimo ou do máximo por saque. | Veja o campo fields. | Exemplo de corpo da requisição: ```json { "amount_cents": 100000 } ``` Exemplo de resposta (201): ```json { "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f", "status": "requested", "amount_cents": 100000, "fee_cents": 0, "reason": null, "payout_key": "**.***.***/****-95", "created_at": "2026-11-23T11:00:00Z", "paid_at": null } ``` Exemplo com cURL: ```bash curl --request POST \ --url 'https://api.redeutopia.com/v1/withdrawals' \ --header "Authorization: Bearer $PAYMENTS_API_KEY" \ --header 'Idempotency-Key: pedido-1234' \ --header 'Content-Type: application/json' \ --data '{ "amount_cents": 100000 }' ``` --- # Listar saques Lista os seus saques, do mais novo para o mais antigo, com filtro de status e paginação por cursor. Endpoint: GET https://api.redeutopia.com/v1/withdrawals Escopo necessário: WITHDRAWAL:READ ## Parâmetros | Parâmetro | Descrição | | --- | --- | | status | Filtra por status: requested, approved, paid, rejected ou failed. | | limit | Quantos itens por página, de 1 a 100. Padrão: 20. | | cursor | O next_cursor da página anterior. Veja Paginação (https://docs.redeutopia.com/listar-pagamentos#paginacao). | ## Resposta | Campo | Tipo | Descrição | | --- | --- | --- | | data | array | Os saques desta página. Cada um tem id, status, amount_cents, fee_cents, reason, payout_key, created_at e paid_at, como em Pedir um saque (https://docs.redeutopia.com/pedir-saque). | | next_cursor | string | Cursor da próxima página. Não vem na última página. | ## Erros | HTTP | Código | Quando acontece | O que fazer | | --- | --- | --- | --- | | 400 | invalid_request | Parâmetro desconhecido ou inválido. | Confira os parâmetros desta página. | Exemplo de resposta (200): ```json { "data": [ { "id": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f", "status": "paid", "amount_cents": 100000, "fee_cents": 0, "reason": null, "payout_key": "**.***.***/****-95", "created_at": "2026-11-23T11:00:00Z", "paid_at": "2026-11-23T15:10:00Z" } ] } ``` Exemplo com cURL: ```bash curl --request GET \ --url 'https://api.redeutopia.com/v1/withdrawals?status=paid' \ --header "Authorization: Bearer $PAYMENTS_API_KEY" ``` --- # Listar infrações e reembolsos Lista as infrações (contestações) e os reembolsos concluídos de um período, com filtros e paginação por cursor. Endpoint: GET https://api.redeutopia.com/v1/infractions Escopo necessário: INFRACTION:READ Cada item é uma infração (kind: infraction) ou um reembolso concluído (kind: refund). Veja como as infrações funcionam em Infrações (https://docs.redeutopia.com/infracoes). ## Parâmetros | Parâmetro | Descrição | | --- | --- | | period | today, month (padrão), 30d, 90d, year ou custom. Os dias seguem o fuso America/Sao_Paulo. | | from | Com period=custom: data inicial, no formato AAAA-MM-DD. | | to | Com period=custom: data final, no formato AAAA-MM-DD. | | kind | infraction ou refund. | | status | Infração: open, in_review, closed_merchant ou closed_payer. Reembolso: completed. | | reason | Filtra pelo motivo. | | q | Busca pelo nome do cliente ou pelo id, até 60 caracteres. | | limit | Quantos itens por página, de 1 a 100. Padrão: 20. | | cursor | O next_cursor da página anterior. | ## Resposta | Campo | Tipo | Descrição | | --- | --- | --- | | data | array | Os itens desta página, no formato de Buscar uma infração (https://docs.redeutopia.com/buscar-infracao) sem os dados da venda e o histórico. | | next_cursor | string | Cursor da próxima página. Não vem na última página. | ## Erros | HTTP | Código | Quando acontece | O que fazer | | --- | --- | --- | --- | | 400 | invalid_request | Parâmetro desconhecido ou inválido. | Confira os parâmetros desta página. | | 400 | invalid_period | Período inválido. | Use datas até hoje, com no máximo 24 meses. | Exemplo de resposta (200): ```json { "data": [ { "id": "6d7e8f9a-0b1c-4d2e-8f3a-4b5c6d7e8f9a", "kind": "infraction", "at": "2026-11-24T13:00:00Z", "payment_id": "0b5c1f7e-4a8d-4f2b-9c3e-6d7a8b9c0d1e", "customer": "Maria Silva", "reason": "fraud", "amount_cents": 15000, "status": "open", "due_at": "2026-12-01T13:00:00Z" } ] } ``` Exemplo com cURL: ```bash curl --request GET \ --url 'https://api.redeutopia.com/v1/infractions?period=30d&kind=infraction' \ --header "Authorization: Bearer $PAYMENTS_API_KEY" ``` --- # Buscar uma infração Devolve uma infração ou um reembolso, com os dados da venda e o histórico. Endpoint: GET https://api.redeutopia.com/v1/infractions/{id} Escopo necessário: INFRACTION:READ Prefira o webhook: os eventos infraction.opened e infraction.updated avisam cada mudança. ## Resposta | Campo | Tipo | Descrição | | --- | --- | --- | | id | string | Id do item. | | kind | string | infraction ou refund. | | at | string (ISO 8601) | Quando a infração foi aberta ou o reembolso foi concluído. | | payment_id | string | Id do pagamento contestado ou devolvido. | | customer | string | Nome de quem pagou. | | reason | string | Motivo: fraud, operational_failure, customer_request, duplicate, infraction ou other. | | amount_cents | integer | Valor contestado ou devolvido, em centavos. | | status | string | Status atual. Veja os status (https://docs.redeutopia.com/infracoes#status-da-infracao). | | due_at | string (ISO 8601) \| null | Prazo da análise, quando houver. | | sale_amount_cents | integer | Valor da venda, em centavos. | | sale_paid_at | string (ISO 8601) \| null | Quando a venda foi paga. | | sale_method | string | Forma de pagamento da venda. | | pix_end_to_end_id | string | Identificador do Pix no Banco Central. | | timeline | array | Histórico: lista de event (o que aconteceu) e at (quando). | ## Erros | HTTP | Código | Quando acontece | O que fazer | | --- | --- | --- | --- | | 404 | not_found | Não existe item com este id na sua conta. | Confira o id. | Exemplo de resposta (200): ```json { "id": "6d7e8f9a-0b1c-4d2e-8f3a-4b5c6d7e8f9a", "kind": "infraction", "at": "2026-11-24T13:00:00Z", "payment_id": "0b5c1f7e-4a8d-4f2b-9c3e-6d7a8b9c0d1e", "customer": "Maria Silva", "reason": "fraud", "amount_cents": 15000, "status": "open", "due_at": "2026-12-01T13:00:00Z", "sale_amount_cents": 15000, "sale_paid_at": "2026-11-22T15:04:12Z", "sale_method": "PIX", "pix_end_to_end_id": "E00000000202611221504A1B2C3D4E5F6", "timeline": [ { "event": "payment.created", "at": "2026-11-22T15:00:00Z" }, { "event": "payment.paid", "at": "2026-11-22T15:04:12Z" }, { "event": "infraction.open", "at": "2026-11-24T13:00:00Z" } ] } ``` Exemplo com cURL: ```bash curl --request GET \ --url 'https://api.redeutopia.com/v1/infractions/0b5c1f7e-4a8d-4f2b-9c3e-6d7a8b9c0d1e' \ --header "Authorization: Bearer $PAYMENTS_API_KEY" ``` --- # Changelog O que mudou na API e nesta documentação. ## Novembro de 2026 - Webhooks: todo evento traz created_at (RFC 3339, UTC). - Chave Pix de saque: pela API, toda chave passa por análise, inclusive a primeira. - Reembolsos: não podem ser pedidos nem enviados enquanto o pagamento tiver uma infração em aberto (infraction_open); a devolução vai para quem pagou, conforme confirmado pelo banco. - Pagamentos Pix: criar (por valor ou por produtos do catálogo com items), buscar e listar (/v1/payments). - Reembolsos: pedir, listar e buscar (/v1/payments/{id}/refunds, /v1/refunds). - Saldo, chave Pix de saque e saques (/v1/balance, /v1/payout-keys, /v1/withdrawals). - Infrações: listar e buscar (/v1/infractions). - Webhooks assinados para pagamentos, reembolsos, saques e infrações. - Chaves de API com escopos. - Documentação pública com exemplos em cURL, Node.js, PHP e Python, llms.txt, llms-full.txt e openapi.json. - Botão "Fazer com IA" para copiar um prompt pronto de integração. - Pagamentos: QR Code em SVG (pix.qr_svg) ao criar e ao buscar; busca (q) e filtro por período (period, from, to) na lista.