Referência · API v1

Sua operação, conectada.

Gerencie catálogo e estoque, gere cobranças Pix, acompanhe pagamentos, solicite saques e consulte seus dados com uma única chave LoopPay.

Catálogo completo

Produtos, subprodutos, fotos e entregas.

Pagamentos verificados

Confirmação na instituição e crédito sem duplicidade.

Controle por chave

Permissões, idempotência e logs de requisições.

# Domínio público temporário da LoopPay: flowpayments.net.
LOOPPAY_URL=https://flowpayments.net
LOOPPAY_API_KEY=loopSUA_CHAVE_DE_16_CARACTERES

# Base: $LOOPPAY_URL/api/v1

O ambiente sandbox ou produção é definido no servidor da plataforma. A chamada não pode trocar esse ambiente. As moedas EUR, GBP e USDT do cadastro de links não habilitam recebimento via esta API Pix; o recebimento implementado é BRL.

Autenticação e permissões

Crie uma chave em Dashboard → API Keys. Copie o segredo exibido uma única vez e envie Authorization: Bearer SUA_CHAVE. A chave identifica a aplicação; nenhum applicationId enviado pelo cliente muda a loja autorizada. Chaves revogadas ou expiradas retornam 401.

Permissões de escrita exigem também a leitura correspondente na criação da chave. Estoque privado, pagamentos, saques, aprovação de saque, métricas e avaliações têm permissões separadas. Chaves anteriores não recebem novas permissões automaticamente. Integre pelo seu servidor: não há autenticação por cookies nem liberação CORS para expor a chave no site do comprador.

curl "$LOOPPAY_URL/api/v1/products?limit=20&page=1" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY"

Um contrato previsível

Valores, datas e paginação

Valores em centavos inteiros: 2500 = R$ 25,00. Agregados financeiros podem vir como strings para preservar precisão. Datas ISO 8601 em UTC. Listas usam page e limit (1–100, padrão 20), com items, total, page e limit. from é inclusivo; to é exclusivo.

Idempotência e limites

POST, PATCH e PUT exigem Idempotency-Key com UUID. Gere uma vez por operação e reutilize com o mesmo corpo em novas tentativas. Operação concluída retorna replayed: true; outro corpo retorna 409. Até 120 chamadas por minuto por chave; 429 inclui Retry-After: 60. Cobranças e saques também têm limites próprios.

Em 503, a requisição pode ter sido aceita pela instituição. Não crie uma nova cobrança ou saque cegamente. Use operationId para consultar o recurso: em pagamentos, GET /payments?requestKey=operationId; em saques e catálogo, operationId é o ID reservado. Se houver pagamento em creating, POST /payments/id/refresh tenta recuperar a cobrança. Se uma operação permanece em andamento, o mesmo Idempotency-Key retorna 409 em vez de executá-la novamente.

{
  "data": {
    "id": "identificador-do-recurso"
  },
  "requestId": "uuid-da-requisicao"
}

{
  "error": {
    "code": "scope_required",
    "message": "Permissão necessária: payments:write."
  },
  "requestId": "uuid-da-requisicao"
}

200 / 201	Consulta ou alteração concluída / recurso criado.
400 / 413 / 415	Dados inválidos / corpo grande / conteúdo diferente de JSON.
401 / 403	Chave inválida / permissão insuficiente.
404 / 405	Recurso da aplicação não encontrado / método indisponível.
409	Conflito de idempotência, estoque alterado, saldo ou recurso indisponível.
429	Limite de requisições atingido.
503	Banco ou instituição indisponível; consulte o recurso antes de repetir.

Do produto à entrega

01
Crie uma categoria e depois um produto. Nome e preço são obrigatórios; descrição, imagem e subprodutos são opcionais.
02
Para entrega automática, configure deliveryType automatic e cadastre estoque com stockText. Para manual, o vendedor envia o conteúdo depois do pagamento.
03
Se houver variações, crie subprodutos com preço e estoque próprios. Use o id da opção comprada em productId.
04
Gere um pagamento com name, email, productId e quantity. Exiba o br_code como QR Code ou Pix copia e cola.
05
Consulte o estado ou chame refresh. O webhook assinado da Woovi e a reconciliação conferem o pagamento na instituição. Não há endpoint público para forçar aprovação.
06
Em produção, a confirmação credita o valor líquido uma única vez e entrega o estoque. O comprador vê o conteúdo no checkout; a integração consulta /delivery. No sandbox não há crédito real nem consumo de estoque.

Taxa por pagamento: 2% + R$ 0,50, arredondada em centavos. Os dados do estoque ficam criptografados no banco. Um pedido sem estoque suficiente após confirmação fica aguardando o vendedor. A verificação usa a API oficial da Woovi; a chave da instituição fica somente no servidor da plataforma.

Webhooks assinados

Cadastre um destino HTTPS público, selecione eventos e guarde o segredo whsec_. Cada envio usa X-LoopPay-Event-Id, X-LoopPay-Delivery-Id, X-LoopPay-Timestamp e X-LoopPay-Signature. A assinatura é v1=HEX(HMAC-SHA256(secret, timestamp + '.' + corpo bruto)). Valide antes de interpretar o JSON, rejeite timestamps com mais de 5 minutos de diferença e deduplique event.id no banco.

A entrega pode repetir e chegar fora de ordem. Responda 2xx após persistir o evento em uma fila durável. Até 8 tentativas com espera crescente: 1 min, 5 min, 15 min, 1 h, 3 h, 6 h e 24 h. Redirecionamentos não são seguidos. Produtos e avaliações têm environment null; pagamentos e saques respeitam o ambiente selecionado. Eventos não incluem estoque privado ou chave Pix.

O worker deve ser agendado no servidor. O botão Processar pendentes permite processamento manual pelo painel. Testes retornam 202 quando enfileirados, não quando entregues. Consulte tentativas e reprocessamentos em Fluxos → Logs → Webhooks.

Exemplo de validação e guia para IA →

Referência dos endpoints

Catálogo

Listar produtos

GET/api/v1/productsproducts:read

Produtos principais da aplicação. Use q para buscar pelo nome. Os subprodutos têm uma listagem própria.

Não há corpo. Listagens aceitam page e limit. Substitua {id}, quando presente, pelo UUID do recurso.

Resposta de sucesso

{
  "data": {
    "items": [
      {
        "id": "00000000-0000-4000-8000-000000000001",
        "name": "Acesso mensal",
        "description": "Licença digital por 30 dias",
        "price_cents": 2500,
        "delivery_type": "automatic",
        "stock_format": "lines",
        "stock_count": 2,
        "image_url": "https://sua-loja.com/produto.png",
        "parent_id": null,
        "visible": true,
        "checkout_path": "/checkout/00000000-0000-4000-8000-000000000001"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X GET "$LOOPPAY_URL/api/v1/products" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY"

Catálogo

Criar produto

POST/api/v1/productsproducts:write

Cria o produto no banco e retorna o endereço de checkout. Valores recebidos usam camelCase; projeções do banco usam snake_case.

Corpo da requisição · JSON

namestringObrigatório

Nome de 2 a 120 caracteres.

priceCentsintegerObrigatório

Preço unitário em centavos. De 1 a 999999999; preço × quantidade mínima deve ser pelo menos 200.

descriptionstring

Descrição de até 10000 caracteres. Padrão: vazio.

slugstring

Endereço com até 100 caracteres. Gerado a partir do nome se omitido.

comparePriceCentsinteger | null

Preço anterior; deve ser igual ou maior que o preço atual. Padrão: null.

minQuantityinteger

Quantidade mínima de 1 a 10000. Padrão: 1.

maxQuantityinteger

Máximo por pedido, de minQuantity a 10000. Padrão: 10000.

deliveryTypemanual | automatic

manual: entrega pelo vendedor. automatic: consome o estoque após confirmação em produção. Padrão: manual.

stockFormatlines | block

lines: uma unidade por linha. block: todo o texto é uma unidade. Padrão: lines.

stockTextstring

Conteúdo privado de até 100000 caracteres. Exige também stock:write. Omitido na edição preserva o estoque.

instructionsstring

Instruções após pagamento, até 5000 caracteres. Nunca são enviadas ao comprador antes da confirmação.

imageUrlstring

URL HTTPS pública, até 2000 caracteres. Também pode enviar a imagem em /image.

videoUrlstring

URL HTTPS do vídeo, até 2000 caracteres.

categoryIduuid | null

Categoria da mesma aplicação. Padrão: null.

visibleboolean

Exibe e permite a compra quando true. Padrão: true. false preserva o histórico.

Resposta de sucesso

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "name": "Acesso mensal",
    "description": "Licença digital por 30 dias",
    "price_cents": 2500,
    "delivery_type": "automatic",
    "stock_format": "lines",
    "stock_count": 2,
    "image_url": "https://sua-loja.com/produto.png",
    "parent_id": null,
    "visible": true,
    "checkout_path": "/checkout/00000000-0000-4000-8000-000000000001"
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X POST "$LOOPPAY_URL/api/v1/products" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: UUID-UNICO-PARA-ESTA-OPERACAO" \
  -d '{
  "name": "Acesso mensal",
  "priceCents": 2500,
  "description": "Licença por 30 dias",
  "deliveryType": "manual",
  "imageUrl": "https://sua-loja.com/produto.png"
}'

Use uma chave de idempotência UUID real. Nos exemplos, gere uma chave uma única vez e preserve-a para eventuais novas tentativas.

Catálogo

Consultar produto

GET/api/v1/products/{id}products:read

Retorna nome, preço, descrição, foto, estoque disponível, entrega, categoria, parent_id e links. Não retorna conteúdo privado do estoque.

Não há corpo. Listagens aceitam page e limit. Substitua {id}, quando presente, pelo UUID do recurso.

Resposta de sucesso

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "name": "Acesso mensal",
    "description": "Licença digital por 30 dias",
    "price_cents": 2500,
    "delivery_type": "automatic",
    "stock_format": "lines",
    "stock_count": 2,
    "image_url": "https://sua-loja.com/produto.png",
    "parent_id": null,
    "visible": true,
    "checkout_path": "/checkout/00000000-0000-4000-8000-000000000001"
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X GET "$LOOPPAY_URL/api/v1/products/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY"

Catálogo

Atualizar produto

PATCH/api/v1/products/{id}products:write

Envie apenas os campos que deseja alterar. Para desativar sem apagar pedidos, envie visible: false. Ao mudar o formato do estoque ou o tipo de entrega, envie também stockText e tenha stock:write.

Corpo da requisição · JSON

namestring

Nome de 2 a 120 caracteres.

priceCentsinteger

Preço unitário em centavos. De 1 a 999999999; preço × quantidade mínima deve ser pelo menos 200.

descriptionstring

Descrição de até 10000 caracteres. Padrão: vazio.

slugstring

Endereço com até 100 caracteres. Gerado a partir do nome se omitido.

comparePriceCentsinteger | null

Preço anterior; deve ser igual ou maior que o preço atual. Padrão: null.

minQuantityinteger

Quantidade mínima de 1 a 10000. Padrão: 1.

maxQuantityinteger

Máximo por pedido, de minQuantity a 10000. Padrão: 10000.

deliveryTypemanual | automatic

manual: entrega pelo vendedor. automatic: consome o estoque após confirmação em produção. Padrão: manual.

stockFormatlines | block

lines: uma unidade por linha. block: todo o texto é uma unidade. Padrão: lines.

stockTextstring

Conteúdo privado de até 100000 caracteres. Exige também stock:write. Omitido na edição preserva o estoque.

instructionsstring

Instruções após pagamento, até 5000 caracteres. Nunca são enviadas ao comprador antes da confirmação.

imageUrlstring

URL HTTPS pública, até 2000 caracteres. Também pode enviar a imagem em /image.

videoUrlstring

URL HTTPS do vídeo, até 2000 caracteres.

categoryIduuid | null

Categoria da mesma aplicação. Padrão: null.

visibleboolean

Exibe e permite a compra quando true. Padrão: true. false preserva o histórico.

Resposta de sucesso

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "name": "Acesso mensal",
    "description": "Licença digital por 30 dias",
    "price_cents": 2500,
    "delivery_type": "automatic",
    "stock_format": "lines",
    "stock_count": 2,
    "image_url": "https://sua-loja.com/produto.png",
    "parent_id": null,
    "visible": true,
    "checkout_path": "/checkout/00000000-0000-4000-8000-000000000001"
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X PATCH "$LOOPPAY_URL/api/v1/products/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: UUID-UNICO-PARA-ESTA-OPERACAO" \
  -d '{
  "name": "Acesso mensal Premium",
  "priceCents": 3000,
  "visible": true
}'

Use uma chave de idempotência UUID real. Nos exemplos, gere uma chave uma única vez e preserve-a para eventuais novas tentativas.

Mídia

Enviar foto

POST/api/v1/products/{id}/imageproducts:write

Valida a assinatura do arquivo, hospeda no bucket público product-media e vincula ao produto. Até 2 MB; PNG, JPEG ou WebP. Não envie arquivos de entrega neste bucket.

Corpo da requisição · JSON

base64stringObrigatório

Conteúdo do arquivo em base64, sem prefixo data:.

contentTypestringObrigatório

image/png, image/jpeg ou image/webp; deve corresponder ao arquivo.

Resposta de sucesso

{
  "data": {
    "productId": "00000000-0000-4000-8000-000000000001",
    "imageUrl": "https://seu-projeto.supabase.co/storage/v1/object/public/product-media/foto.png"
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X POST "$LOOPPAY_URL/api/v1/products/00000000-0000-4000-8000-000000000001/image" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: UUID-UNICO-PARA-ESTA-OPERACAO" \
  -d '{
  "base64": "BASE64_DO_ARQUIVO",
  "contentType": "image/png"
}'

Use uma chave de idempotência UUID real. Nos exemplos, gere uma chave uma única vez e preserve-a para eventuais novas tentativas.

Subprodutos

Listar subprodutos

GET/api/v1/products/{id}/subproductsproducts:read

Opções independentes do produto principal. Cada opção tem id, nome, preço, descrição, foto e estoque próprios.

Não há corpo. Listagens aceitam page e limit. Substitua {id}, quando presente, pelo UUID do recurso.

Resposta de sucesso

{
  "data": {
    "items": [
      {
        "id": "00000000-0000-4000-8000-000000000001",
        "name": "Acesso mensal",
        "description": "Licença digital por 30 dias",
        "price_cents": 2500,
        "delivery_type": "automatic",
        "stock_format": "lines",
        "stock_count": 2,
        "image_url": "https://sua-loja.com/produto.png",
        "parent_id": null,
        "visible": true,
        "checkout_path": "/checkout/00000000-0000-4000-8000-000000000001"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X GET "$LOOPPAY_URL/api/v1/products/00000000-0000-4000-8000-000000000001/subproducts" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY"

Subprodutos

Criar subproduto

POST/api/v1/products/{id}/subproductsproducts:write

Usa os mesmos campos de um produto. Até 50 opções por produto, sem níveis aninhados. Para editar depois, use PATCH /products/{id_do_subproduto}. Comprar usa productId do subproduto. O produto principal continua sendo uma opção.

Corpo da requisição · JSON

namestringObrigatório

Nome de 2 a 120 caracteres.

priceCentsintegerObrigatório

Preço unitário em centavos. De 1 a 999999999; preço × quantidade mínima deve ser pelo menos 200.

descriptionstring

Descrição de até 10000 caracteres. Padrão: vazio.

slugstring

Endereço com até 100 caracteres. Gerado a partir do nome se omitido.

comparePriceCentsinteger | null

Preço anterior; deve ser igual ou maior que o preço atual. Padrão: null.

minQuantityinteger

Quantidade mínima de 1 a 10000. Padrão: 1.

maxQuantityinteger

Máximo por pedido, de minQuantity a 10000. Padrão: 10000.

deliveryTypemanual | automatic

manual: entrega pelo vendedor. automatic: consome o estoque após confirmação em produção. Padrão: manual.

stockFormatlines | block

lines: uma unidade por linha. block: todo o texto é uma unidade. Padrão: lines.

stockTextstring

Conteúdo privado de até 100000 caracteres. Exige também stock:write. Omitido na edição preserva o estoque.

instructionsstring

Instruções após pagamento, até 5000 caracteres. Nunca são enviadas ao comprador antes da confirmação.

imageUrlstring

URL HTTPS pública, até 2000 caracteres. Também pode enviar a imagem em /image.

videoUrlstring

URL HTTPS do vídeo, até 2000 caracteres.

categoryIduuid | null

Categoria da mesma aplicação. Padrão: null.

visibleboolean

Exibe e permite a compra quando true. Padrão: true. false preserva o histórico.

Resposta de sucesso

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "name": "Acesso mensal",
    "description": "Licença digital por 30 dias",
    "price_cents": 2500,
    "delivery_type": "automatic",
    "stock_format": "lines",
    "stock_count": 2,
    "image_url": "https://sua-loja.com/produto.png",
    "parent_id": "00000000-0000-4000-8000-000000000001",
    "visible": true,
    "checkout_path": "/checkout/00000000-0000-4000-8000-000000000001"
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X POST "$LOOPPAY_URL/api/v1/products/00000000-0000-4000-8000-000000000001/subproducts" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: UUID-UNICO-PARA-ESTA-OPERACAO" \
  -d '{
  "name": "Acesso anual",
  "priceCents": 24000,
  "description": "12 meses de acesso",
  "deliveryType": "manual"
}'

Use uma chave de idempotência UUID real. Nos exemplos, gere uma chave uma única vez e preserve-a para eventuais novas tentativas.

Estoque e entrega

Consultar estoque privado

GET/api/v1/products/{id}/stockstock:read

Retorna o conteúdo descriptografado somente para a integração autorizada. A versão deve acompanhar a substituição do estoque. Não exponha esta chamada no navegador do comprador.

Não há corpo. Listagens aceitam page e limit. Substitua {id}, quando presente, pelo UUID do recurso.

Resposta de sucesso

{
  "data": {
    "productId": "00000000-0000-4000-8000-000000000001",
    "stockText": "LICENCA-A\nLICENCA-B",
    "stockCount": 2,
    "stockFormat": "lines",
    "version": "2026-11-02T18:00:00.000Z"
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X GET "$LOOPPAY_URL/api/v1/products/00000000-0000-4000-8000-000000000001/stock" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY"

Estoque e entrega

Substituir estoque

PUT/api/v1/products/{id}/stockstock:write

Substitui todo o conteúdo, não acrescenta. Para repor, leia a versão atual e envie o conteúdo desejado. Se outra operação alterou o produto, retorna 409 stock_changed. Estoque automático é consumido uma única vez por pagamento confirmado.

Corpo da requisição · JSON

stockTextstringObrigatório

Até 100000 caracteres; linhas vazias não contam.

stockFormatlines | blockObrigatório

Uma unidade por linha ou todo o conteúdo em uma unidade.

versionstringObrigatório

Valor version da consulta de estoque.

Resposta de sucesso

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "stock_count": 2,
    "stock_format": "lines",
    "updated_at": "2026-11-02T18:01:00Z"
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X PUT "$LOOPPAY_URL/api/v1/products/00000000-0000-4000-8000-000000000001/stock" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: UUID-UNICO-PARA-ESTA-OPERACAO" \
  -d '{
  "stockText": "LICENCA-A\nLICENCA-B",
  "stockFormat": "lines",
  "version": "2026-11-02T18:00:00.000Z"
}'

Use uma chave de idempotência UUID real. Nos exemplos, gere uma chave uma única vez e preserve-a para eventuais novas tentativas.

Categorias

Listar categorias

GET/api/v1/categoriesproducts:read

Categorias da aplicação, paginadas.

Não há corpo. Listagens aceitam page e limit. Substitua {id}, quando presente, pelo UUID do recurso.

Resposta de sucesso

{
  "data": {
    "items": [
      {
        "id": "00000000-0000-4000-8000-000000000001",
        "name": "Licenças",
        "slug": "licencas",
        "visible": true
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X GET "$LOOPPAY_URL/api/v1/categories" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY"

Categorias

Criar categoria

POST/api/v1/categoriesproducts:write

Organiza os produtos da aplicação.

Corpo da requisição · JSON

namestringObrigatório

2 a 80 caracteres; não pode ser Sem categoria.

subtitlestring

Até 160 caracteres.

descriptionstring

Até 2000 caracteres.

slugstring

Até 100 caracteres; gerado do nome se omitido.

visibleboolean

Padrão: true.

Resposta de sucesso

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "name": "Licenças",
    "slug": "licencas",
    "visible": true
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X POST "$LOOPPAY_URL/api/v1/categories" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: UUID-UNICO-PARA-ESTA-OPERACAO" \
  -d '{
  "name": "Licenças",
  "subtitle": "Entrega digital",
  "visible": true
}'

Use uma chave de idempotência UUID real. Nos exemplos, gere uma chave uma única vez e preserve-a para eventuais novas tentativas.

Categorias

Editar categoria

PATCH/api/v1/categories/{id}products:write

Aceita os mesmos campos da criação; envie somente as alterações.

Envie um objeto JSON. Use a mesma chave de idempotência ao repetir esta operação.

Resposta de sucesso

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "name": "Licenças digitais",
    "visible": true
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X PATCH "$LOOPPAY_URL/api/v1/categories/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: UUID-UNICO-PARA-ESTA-OPERACAO" \
  -d '{
  "name": "Licenças digitais",
  "visible": true
}'

Use uma chave de idempotência UUID real. Nos exemplos, gere uma chave uma única vez e preserve-a para eventuais novas tentativas.

Pagamentos Pix

Gerar pagamento

POST/api/v1/paymentspayments:write

Gera cobrança Pix dinâmica na Woovi e salva a reserva na aplicação da chave. Informe productId e quantity para vender um produto/subproduto; o servidor determina o preço. Para cobrança avulsa, omita productId e informe title e amountCents. Moeda de recebimento: BRL.

Corpo da requisição · JSON

namestringObrigatório

Nome do comprador; 2 a 100 caracteres.

emailstringObrigatório

E-mail válido, até 254 caracteres.

productIduuid

ID do produto ou subproduto da aplicação. Não enviar amountCents neste modo.

quantityinteger

Padrão 1; deve respeitar os limites e o estoque do produto.

titlestring

Obrigatório para cobrança avulsa; 2 a 120 caracteres.

amountCentsinteger

Obrigatório para cobrança avulsa; 200 a 100000000 centavos.

Resposta de sucesso

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "environment": "sandbox",
    "amount_cents": 2500,
    "fee_cents": 100,
    "net_cents": 2400,
    "status": "pending",
    "br_code": "000201…",
    "expires_at": "2026-11-02T19:00:00Z",
    "paid_at": null,
    "kind": "product",
    "productId": "00000000-0000-4000-8000-000000000001",
    "quantity": 1,
    "requestKey": "00000000-0000-4000-8000-000000000001"
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X POST "$LOOPPAY_URL/api/v1/payments" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: UUID-UNICO-PARA-ESTA-OPERACAO" \
  -d '{
  "productId": "00000000-0000-4000-8000-000000000001",
  "quantity": 1,
  "name": "Cliente exemplo",
  "email": "cliente@exemplo.com"
}'

Use uma chave de idempotência UUID real. Nos exemplos, gere uma chave uma única vez e preserve-a para eventuais novas tentativas.

Pagamentos Pix

Listar pagamentos

GET/api/v1/paymentspayments:read

Filtre por status (creating, pending, completed, expired) ou requestKey retornado na criação. Ambiente definido pelo servidor. A consulta não força confirmação na instituição.

Não há corpo. Listagens aceitam page e limit. Substitua {id}, quando presente, pelo UUID do recurso.

Resposta de sucesso

{
  "data": {
    "items": [
      {
        "id": "00000000-0000-4000-8000-000000000001",
        "environment": "sandbox",
        "amount_cents": 2500,
        "fee_cents": 100,
        "net_cents": 2400,
        "status": "pending",
        "br_code": "000201…",
        "expires_at": "2026-11-02T19:00:00Z",
        "paid_at": null,
        "kind": "product",
        "productId": "00000000-0000-4000-8000-000000000001",
        "quantity": 1
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X GET "$LOOPPAY_URL/api/v1/payments" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY"

Pagamentos Pix

Consultar pagamento

GET/api/v1/payments/{id}payments:read

Retorna o estado salvo. completed é confirmação; pending não libera saldo. Conteúdo de entrega fica na rota /delivery.

Não há corpo. Listagens aceitam page e limit. Substitua {id}, quando presente, pelo UUID do recurso.

Resposta de sucesso

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "environment": "sandbox",
    "amount_cents": 2500,
    "fee_cents": 100,
    "net_cents": 2400,
    "status": "pending",
    "br_code": "000201…",
    "expires_at": "2026-11-02T19:00:00Z",
    "paid_at": null,
    "kind": "product",
    "productId": "00000000-0000-4000-8000-000000000001",
    "quantity": 1
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X GET "$LOOPPAY_URL/api/v1/payments/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY"

Pagamentos Pix

Validar pagamento na instituição

POST/api/v1/payments/{id}/refreshpayments:write

Consulta a cobrança na Woovi e confere correlação, valor e ambiente. Somente uma confirmação válida credita a carteira; chamadas repetidas não duplicam crédito ou entrega. Não aceita status informado pelo cliente. Envie {} no corpo.

Envie um objeto JSON. Use a mesma chave de idempotência ao repetir esta operação.

Resposta de sucesso

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "environment": "sandbox",
    "amount_cents": 2500,
    "fee_cents": 100,
    "net_cents": 2400,
    "status": "completed",
    "br_code": "000201…",
    "expires_at": "2026-11-02T19:00:00Z",
    "paid_at": "2026-11-02T18:02:00Z",
    "kind": "product",
    "productId": "00000000-0000-4000-8000-000000000001",
    "quantity": 1
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X POST "$LOOPPAY_URL/api/v1/payments/00000000-0000-4000-8000-000000000001/refresh" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: UUID-UNICO-PARA-ESTA-OPERACAO" \
  -d '{}'

Use uma chave de idempotência UUID real. Nos exemplos, gere uma chave uma única vez e preserve-a para eventuais novas tentativas.

Estoque e entrega

Consultar entrega do pedido

GET/api/v1/payments/{id}/deliveryorders:read

Conteúdo e instruções ficam disponíveis após confirmação em produção. No modo automático, o comprador também os vê no checkout original. No sandbox, o estoque não é consumido e content é null.

Não há corpo. Listagens aceitam page e limit. Substitua {id}, quando presente, pelo UUID do recurso.

Resposta de sucesso

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "status": "delivered",
    "content": "LICENCA-A",
    "instructions": "Use esta licença no seu aplicativo."
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X GET "$LOOPPAY_URL/api/v1/payments/00000000-0000-4000-8000-000000000001/delivery" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY"

Estoque e entrega

Registrar entrega manual

POST/api/v1/payments/{id}/deliveryorders:write

Salva uma entrega privada para produto pago em produção com delivery_status waiting_seller. O conteúdo aparece no checkout do comprador. Não substitui uma entrega já concluída.

Corpo da requisição · JSON

contentstringObrigatório

Conteúdo de entrega com 1 a 100000 caracteres.

Resposta de sucesso

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "delivery_status": "delivered"
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X POST "$LOOPPAY_URL/api/v1/payments/00000000-0000-4000-8000-000000000001/delivery" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: UUID-UNICO-PARA-ESTA-OPERACAO" \
  -d '{
  "content": "Seu acesso está disponível: instruções de ativação."
}'

Use uma chave de idempotência UUID real. Nos exemplos, gere uma chave uma única vez e preserve-a para eventuais novas tentativas.

Saques

Criar saque

POST/api/v1/withdrawalswithdrawals:write

Reserva saldo e cria a transferência sem aprová-la. Tarifa R$ 0,70; mínimo líquido R$ 10,00. O saldo é da conta do proprietário e é compartilhado entre lojas. O ambiente acompanha a configuração do servidor. Não é necessário chamar Account Data Check.

Corpo da requisição · JSON

keyTypeCPF | CNPJ | EMAIL | PHONE | RANDOMObrigatório

Tipo da chave Pix.

keystringObrigatório

Chave de destino; telefone em formato internacional. Guardada criptografada.

amountCentsintegerObrigatório

Valor líquido, ou total caso deductFee seja true. Máximo 100000000.

deductFeeboolean

false: soma tarifa ao total reservado. true: deduz tarifa do valor informado.

Resposta de sucesso

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "pix_key_type": "EMAIL",
    "pix_key_mask": "•••• .com",
    "amount_cents": 1000,
    "fee_cents": 70,
    "total_cents": 1070,
    "status": "created",
    "provider_status": "CREATED"
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X POST "$LOOPPAY_URL/api/v1/withdrawals" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: UUID-UNICO-PARA-ESTA-OPERACAO" \
  -d '{
  "keyType": "EMAIL",
  "key": "financeiro@exemplo.com",
  "amountCents": 1000,
  "deductFee": false
}'

Use uma chave de idempotência UUID real. Nos exemplos, gere uma chave uma única vez e preserve-a para eventuais novas tentativas.

Saques

Histórico de saques

GET/api/v1/withdrawalswithdrawals:read

Lista solicitações da aplicação no ambiente atual. As chaves Pix aparecem mascaradas.

Não há corpo. Listagens aceitam page e limit. Substitua {id}, quando presente, pelo UUID do recurso.

Resposta de sucesso

{
  "data": {
    "environment": "sandbox",
    "items": [
      {
        "id": "00000000-0000-4000-8000-000000000001",
        "pix_key_type": "EMAIL",
        "pix_key_mask": "•••• .com",
        "amount_cents": 1000,
        "fee_cents": 70,
        "total_cents": 1070,
        "status": "created",
        "provider_status": "CREATED"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X GET "$LOOPPAY_URL/api/v1/withdrawals" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY"

Saques

Consultar saque

GET/api/v1/withdrawals/{id}withdrawals:read

Consulta local paginada, com items contendo no máximo a solicitação informada.

Não há corpo. Listagens aceitam page e limit. Substitua {id}, quando presente, pelo UUID do recurso.

Resposta de sucesso

{
  "data": {
    "environment": "sandbox",
    "items": [
      {
        "id": "00000000-0000-4000-8000-000000000001",
        "pix_key_type": "EMAIL",
        "pix_key_mask": "•••• .com",
        "amount_cents": 1000,
        "fee_cents": 70,
        "total_cents": 1070,
        "status": "created",
        "provider_status": "CREATED"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X GET "$LOOPPAY_URL/api/v1/withdrawals/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY"

Saques

Aprovar envio

POST/api/v1/withdrawals/{id}/approvewithdrawals_approval:write

Autoriza o envio à chave cadastrada. Use uma chave com esta permissão apenas no servidor. CREATED ainda não é transferência concluída; completed exige CONFIRMED da instituição. Envie {}.

Envie um objeto JSON. Use a mesma chave de idempotência ao repetir esta operação.

Resposta de sucesso

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "pix_key_type": "EMAIL",
    "pix_key_mask": "•••• .com",
    "amount_cents": 1000,
    "fee_cents": 70,
    "total_cents": 1070,
    "status": "processing",
    "provider_status": "APPROVED"
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X POST "$LOOPPAY_URL/api/v1/withdrawals/00000000-0000-4000-8000-000000000001/approve" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: UUID-UNICO-PARA-ESTA-OPERACAO" \
  -d '{}'

Use uma chave de idempotência UUID real. Nos exemplos, gere uma chave uma única vez e preserve-a para eventuais novas tentativas.

Saques

Conferir saque na instituição

POST/api/v1/withdrawals/{id}/refreshwithdrawals:write

Atualiza o estado pela Woovi. Falha definitiva libera a reserva uma única vez; resposta desconhecida mantém o valor reservado. Em produção, chamadas não retornam de completed para failed. Envie {}.

Envie um objeto JSON. Use a mesma chave de idempotência ao repetir esta operação.

Resposta de sucesso

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "pix_key_type": "EMAIL",
    "pix_key_mask": "•••• .com",
    "amount_cents": 1000,
    "fee_cents": 70,
    "total_cents": 1070,
    "status": "completed",
    "provider_status": "CONFIRMED"
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X POST "$LOOPPAY_URL/api/v1/withdrawals/00000000-0000-4000-8000-000000000001/refresh" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: UUID-UNICO-PARA-ESTA-OPERACAO" \
  -d '{}'

Use uma chave de idempotência UUID real. Nos exemplos, gere uma chave uma única vez e preserve-a para eventuais novas tentativas.

Dados e relatórios

Saldo disponível

GET/api/v1/balancemetrics:read

Saldo em centavos como string. Em produção, considera a carteira real e reservas de saque. No sandbox, considera somente os pagamentos simulados e saques de teste.

Não há corpo. Listagens aceitam page e limit. Substitua {id}, quando presente, pelo UUID do recurso.

Resposta de sucesso

{
  "data": {
    "currency": "BRL",
    "environment": "sandbox",
    "availableCents": "2400",
    "scope": "owner_account",
    "sharedAcrossApplications": true
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X GET "$LOOPPAY_URL/api/v1/balance" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY"

Dados e relatórios

Receita, vendas e MRR

GET/api/v1/metricsmetrics:read

Parâmetros from e to em ISO 8601; início inclusivo e fim exclusivo. Padrão: últimos 30 dias. Receita exclui depósitos. MRR usa assinaturas ativas e pagas, normalizadas em 30 dias; é indicador de recorrência, não cobrança automática.

Não há corpo. Listagens aceitam page e limit. Substitua {id}, quando presente, pelo UUID do recurso.

Resposta de sucesso

{
  "data": {
    "currency": "BRL",
    "environment": "production",
    "grossCents": "2500",
    "feeCents": "100",
    "netCents": "2400",
    "approvedPayments": 1,
    "sales": 1,
    "pendingPayments": 0,
    "mrrCents": "2500",
    "mrrBasis": "30_days_active_paid_subscriptions"
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X GET "$LOOPPAY_URL/api/v1/metrics" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY"

Dados e relatórios

Relatório de pagamentos

GET/api/v1/reportsmetrics:read

Exportação JSON paginada com valores brutos, taxas, líquidos, ambiente, datas e estado. Use from e to (ISO 8601). Datas UTC; centavos inteiros. Percorra as páginas até atingir total.

Não há corpo. Listagens aceitam page e limit. Substitua {id}, quando presente, pelo UUID do recurso.

Resposta de sucesso

{
  "data": {
    "items": [
      {
        "id": "00000000-0000-4000-8000-000000000001",
        "environment": "sandbox",
        "amount_cents": 2500,
        "fee_cents": 100,
        "net_cents": 2400,
        "status": "pending",
        "br_code": "000201…",
        "expires_at": "2026-11-02T19:00:00Z",
        "paid_at": null,
        "kind": "product",
        "productId": "00000000-0000-4000-8000-000000000001",
        "quantity": 1
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20,
    "environment": "sandbox",
    "currency": "BRL"
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X GET "$LOOPPAY_URL/api/v1/reports" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY"

Clientes e pedidos

Listar clientes

GET/api/v1/customerscustomers:read

Clientes da aplicação, criados por compras reais ou pelo painel. Dados pessoais devem ser utilizados somente pela integração autorizada.

Não há corpo. Listagens aceitam page e limit. Substitua {id}, quando presente, pelo UUID do recurso.

Resposta de sucesso

{
  "data": {
    "items": [
      {
        "id": "00000000-0000-4000-8000-000000000001",
        "name": "Cliente exemplo",
        "email": "cliente@exemplo.com",
        "tags": []
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X GET "$LOOPPAY_URL/api/v1/customers" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY"

Clientes e pedidos

Listar pedidos

GET/api/v1/ordersorders:read

Pedidos registrados em produção, com produto, valor, cliente, estado e referência. Pagamentos de sandbox não geram pedidos reais.

Não há corpo. Listagens aceitam page e limit. Substitua {id}, quando presente, pelo UUID do recurso.

Resposta de sucesso

{
  "data": {
    "items": [
      {
        "id": "00000000-0000-4000-8000-000000000001",
        "order_reference": "00000000-0000-4000-8000-000000000001",
        "product_name": "Acesso mensal",
        "amount_cents": 2500,
        "status": "approved",
        "delivery_type": "automatic"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X GET "$LOOPPAY_URL/api/v1/orders" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY"

Avaliações

Consultar avaliações

GET/api/v1/reviewsreviews:read

Filtro status: pending, published ou hidden. A API não fabrica avaliações: o envio pelo comprador continua exigindo uma compra verificada e autenticação.

Não há corpo. Listagens aceitam page e limit. Substitua {id}, quando presente, pelo UUID do recurso.

Resposta de sucesso

{
  "data": {
    "items": [
      {
        "id": "00000000-0000-4000-8000-000000000001",
        "product_id": "00000000-0000-4000-8000-000000000001",
        "display_name": "Cliente",
        "rating": 5,
        "body": "Entrega rápida.",
        "status": "pending",
        "owner_reply": null
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X GET "$LOOPPAY_URL/api/v1/reviews" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY"

Avaliações

Moderar e responder

PATCH/api/v1/reviews/{id}reviews:write

Publica, oculta ou responde uma avaliação recebida. Não altera a nota nem o texto do comprador.

Corpo da requisição · JSON

statuspending | published | hidden

Novo estado da moderação.

replystring

Resposta de até 2000 caracteres. Vazio remove a resposta.

Resposta de sucesso

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "status": "published",
    "owner_reply": "Obrigado pela confiança!"
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X PATCH "$LOOPPAY_URL/api/v1/reviews/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: UUID-UNICO-PARA-ESTA-OPERACAO" \
  -d '{
  "status": "published",
  "reply": "Obrigado pela confiança!"
}'

Use uma chave de idempotência UUID real. Nos exemplos, gere uma chave uma única vez e preserve-a para eventuais novas tentativas.

Logs

Consultar logs da API

GET/api/v1/logslogs:read

Requisições autenticadas da aplicação: método, rota normalizada, HTTP status, duração, erro, ID da chave e requestId. Sem cabeçalhos de autenticação, corpo, conteúdo do estoque ou chave Pix. Também disponível em Fluxos → Logs → Requisições da API.

Não há corpo. Listagens aceitam page e limit. Substitua {id}, quando presente, pelo UUID do recurso.

Resposta de sucesso

{
  "data": {
    "items": [
      {
        "id": "00000000-0000-4000-8000-000000000001",
        "method": "POST",
        "route": "/api/v1/payments",
        "status": 201,
        "duration_ms": 340,
        "error_code": null
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X GET "$LOOPPAY_URL/api/v1/logs" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY"

Categorias

Consultar categorias por ID

GET/api/v1/categories/{id}products:read

Consulta filtrada pelo UUID. A resposta usa items com no máximo um recurso da aplicação. Categorias da aplicação, paginadas.

Não há corpo. Listagens aceitam page e limit. Substitua {id}, quando presente, pelo UUID do recurso.

Resposta de sucesso

{
  "data": {
    "items": [
      {
        "id": "00000000-0000-4000-8000-000000000001",
        "name": "Licenças",
        "slug": "licencas",
        "visible": true
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X GET "$LOOPPAY_URL/api/v1/categories/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY"

Clientes e pedidos

Consultar clientes por ID

GET/api/v1/customers/{id}customers:read

Consulta filtrada pelo UUID. A resposta usa items com no máximo um recurso da aplicação. Clientes da aplicação, criados por compras reais ou pelo painel. Dados pessoais devem ser utilizados somente pela integração autorizada.

Não há corpo. Listagens aceitam page e limit. Substitua {id}, quando presente, pelo UUID do recurso.

Resposta de sucesso

{
  "data": {
    "items": [
      {
        "id": "00000000-0000-4000-8000-000000000001",
        "name": "Cliente exemplo",
        "email": "cliente@exemplo.com",
        "tags": []
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X GET "$LOOPPAY_URL/api/v1/customers/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY"

Clientes e pedidos

Consultar pedidos por ID

GET/api/v1/orders/{id}orders:read

Consulta filtrada pelo UUID. A resposta usa items com no máximo um recurso da aplicação. Pedidos registrados em produção, com produto, valor, cliente, estado e referência. Pagamentos de sandbox não geram pedidos reais.

Não há corpo. Listagens aceitam page e limit. Substitua {id}, quando presente, pelo UUID do recurso.

Resposta de sucesso

{
  "data": {
    "items": [
      {
        "id": "00000000-0000-4000-8000-000000000001",
        "order_reference": "00000000-0000-4000-8000-000000000001",
        "product_name": "Acesso mensal",
        "amount_cents": 2500,
        "status": "approved",
        "delivery_type": "automatic"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X GET "$LOOPPAY_URL/api/v1/orders/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY"

Avaliações

Consultar avaliações por ID

GET/api/v1/reviews/{id}reviews:read

Consulta filtrada pelo UUID. A resposta usa items com no máximo um recurso da aplicação. Filtro status: pending, published ou hidden. A API não fabrica avaliações: o envio pelo comprador continua exigindo uma compra verificada e autenticação.

Não há corpo. Listagens aceitam page e limit. Substitua {id}, quando presente, pelo UUID do recurso.

Resposta de sucesso

{
  "data": {
    "items": [
      {
        "id": "00000000-0000-4000-8000-000000000001",
        "product_id": "00000000-0000-4000-8000-000000000001",
        "display_name": "Cliente",
        "rating": 5,
        "body": "Entrega rápida.",
        "status": "pending",
        "owner_reply": null
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X GET "$LOOPPAY_URL/api/v1/reviews/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY"

Webhooks

Listar destinos

GET/api/v1/webhookswebhooks:read

Lista destinos da aplicação, sem o segredo de assinatura. Até 10 destinos não arquivados.

Não há corpo. Listagens aceitam page e limit. Substitua {id}, quando presente, pelo UUID do recurso.

Resposta de sucesso

{
  "data": {
    "items": [
      {
        "id": "00000000-0000-4000-8000-000000000001",
        "name": "Sistema de pedidos",
        "url": "https://seu-sistema.com/webhooks/looppay",
        "events": [
          "payment.completed",
          "delivery.completed"
        ],
        "environment": "sandbox",
        "enabled": true,
        "version": 1
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X GET "$LOOPPAY_URL/api/v1/webhooks" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY"

Webhooks

Consultar destino

GET/api/v1/webhooks/{id}webhooks:read

Consulta nome, URL, eventos, ambiente, estado e versão. O segredo não é retornado.

Não há corpo. Listagens aceitam page e limit. Substitua {id}, quando presente, pelo UUID do recurso.

Resposta de sucesso

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "name": "Sistema de pedidos",
    "url": "https://seu-sistema.com/webhooks/looppay",
    "events": [
      "payment.completed",
      "delivery.completed"
    ],
    "environment": "sandbox",
    "enabled": true,
    "version": 1
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X GET "$LOOPPAY_URL/api/v1/webhooks/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY"

Webhooks

Cadastrar webhook

POST/api/v1/webhookswebhooks:write

Cria um destino HTTPS público. Retorna o segredo apenas na resposta original, criptografado no banco. A repetição idempotente retorna metadados sem secret. Se perder o segredo, use /rotate.

Corpo da requisição · JSON

namestringObrigatório

Nome de 2 a 80 caracteres.

urlstringObrigatório

URL HTTPS pública na porta 443, até 2000 caracteres. Sem usuário, senha, fragmento ou IP literal. Segredos não devem ser colocados na URL.

eventsarrayObrigatório

Lista dos eventos documentados. Ao menos um. Ex.: payment.completed e delivery.completed.

environmentsandbox | productionObrigatório

Filtra pagamentos e saques. Produtos e avaliações são eventos de catálogo, com environment null.

enabledbooleanObrigatório

true ativa; false pausa.

Resposta de sucesso

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "name": "Sistema de pedidos",
    "url": "https://seu-sistema.com/webhooks/looppay",
    "events": [
      "payment.completed",
      "delivery.completed"
    ],
    "environment": "sandbox",
    "enabled": true,
    "version": 1,
    "secret": "whsec_SEGREDO_DE_ASSINATURA"
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X POST "$LOOPPAY_URL/api/v1/webhooks" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: UUID-UNICO-PARA-ESTA-OPERACAO" \
  -d '{
  "name": "Sistema de pedidos",
  "url": "https://seu-sistema.com/webhooks/looppay",
  "events": [
    "payment.completed",
    "delivery.completed"
  ],
  "environment": "sandbox",
  "enabled": true
}'

Use uma chave de idempotência UUID real. Nos exemplos, gere uma chave uma única vez e preserve-a para eventuais novas tentativas.

Webhooks

Alterar ou pausar destino

PATCH/api/v1/webhooks/{id}webhooks:write

Envie somente os campos desejados. Mudanças se aplicam às tentativas futuras; uma requisição já em andamento pode terminar no destino anterior. Tentativas de um destino pausado são canceladas ao serem processadas.

Corpo da requisição · JSON

namestring

Nome de 2 a 80 caracteres.

urlstring

URL HTTPS pública na porta 443, até 2000 caracteres. Sem usuário, senha, fragmento ou IP literal. Segredos não devem ser colocados na URL.

eventsarray

Lista dos eventos documentados. Ao menos um. Ex.: payment.completed e delivery.completed.

environmentsandbox | production

Filtra pagamentos e saques. Produtos e avaliações são eventos de catálogo, com environment null.

enabledboolean

true ativa; false pausa.

Resposta de sucesso

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "name": "Sistema de pedidos",
    "url": "https://seu-sistema.com/webhooks/looppay",
    "events": [
      "payment.completed",
      "delivery.completed"
    ],
    "environment": "sandbox",
    "enabled": false,
    "version": 2
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X PATCH "$LOOPPAY_URL/api/v1/webhooks/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: UUID-UNICO-PARA-ESTA-OPERACAO" \
  -d '{
  "enabled": false
}'

Use uma chave de idempotência UUID real. Nos exemplos, gere uma chave uma única vez e preserve-a para eventuais novas tentativas.

Webhooks

Arquivar destino

DELETE/api/v1/webhooks/{id}webhooks:write

Arquiva e desativa o endpoint, preservando o histórico. Envie {} e um Idempotency-Key.

Envie um objeto JSON. Use a mesma chave de idempotência ao repetir esta operação.

Resposta de sucesso

{
  "data": {
    "archived": true
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X DELETE "$LOOPPAY_URL/api/v1/webhooks/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: UUID-UNICO-PARA-ESTA-OPERACAO" \
  -d '{}'

Use uma chave de idempotência UUID real. Nos exemplos, gere uma chave uma única vez e preserve-a para eventuais novas tentativas.

Webhooks

Trocar segredo de assinatura

POST/api/v1/webhooks/{id}/rotatewebhooks:write

Gera e retorna um novo secret apenas na resposta original. O antigo deixa de ser usado nos próximos envios. Atualize o receptor imediatamente; uma requisição já em andamento pode usar o segredo anterior.

Envie um objeto JSON. Use a mesma chave de idempotência ao repetir esta operação.

Resposta de sucesso

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "name": "Sistema de pedidos",
    "url": "https://seu-sistema.com/webhooks/looppay",
    "events": [
      "payment.completed",
      "delivery.completed"
    ],
    "environment": "sandbox",
    "enabled": true,
    "version": 2,
    "secret": "whsec_NOVO_SEGREDO"
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X POST "$LOOPPAY_URL/api/v1/webhooks/00000000-0000-4000-8000-000000000001/rotate" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: UUID-UNICO-PARA-ESTA-OPERACAO" \
  -d '{}'

Use uma chave de idempotência UUID real. Nos exemplos, gere uma chave uma única vez e preserve-a para eventuais novas tentativas.

Webhooks

Enfileirar evento de teste

POST/api/v1/webhooks/{id}/testwebhooks:write

Cria webhook.test para o destino ativo, independente dos eventos selecionados. Não gera pagamentos. HTTP 202 significa enfileirado; acompanhe a entrega. O worker precisa estar agendado.

Envie um objeto JSON. Use a mesma chave de idempotência ao repetir esta operação.

Resposta de sucesso

{
  "data": {
    "eventId": "00000000-0000-4000-8000-000000000001",
    "queued": true
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X POST "$LOOPPAY_URL/api/v1/webhooks/00000000-0000-4000-8000-000000000001/test" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: UUID-UNICO-PARA-ESTA-OPERACAO" \
  -d '{}'

Use uma chave de idempotência UUID real. Nos exemplos, gere uma chave uma única vez e preserve-a para eventuais novas tentativas.

Webhooks

Listar entregas

GET/api/v1/webhooks/{id}/deliverieswebhooks:read

Histórico paginado com HTTP status, tentativas, próxima tentativa e erro. Sem corpo da resposta remota ou segredos.

Não há corpo. Listagens aceitam page e limit. Substitua {id}, quando presente, pelo UUID do recurso.

Resposta de sucesso

{
  "data": {
    "items": [
      {
        "id": "00000000-0000-4000-8000-000000000001",
        "endpoint_id": "00000000-0000-4000-8000-000000000001",
        "event_id": "00000000-0000-4000-8000-000000000001",
        "status": "retrying",
        "attempts": 1,
        "http_status": 500,
        "error_code": "http_error",
        "next_attempt_at": "2026-11-02T18:01:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X GET "$LOOPPAY_URL/api/v1/webhooks/00000000-0000-4000-8000-000000000001/deliveries" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY"

Webhooks

Inspecionar entrega e tentativas

GET/api/v1/webhook-deliveries/{id}webhooks:read

Retorna os metadados da entrega, payload do evento e histórico de tentativas. Status: pending, processing, retrying, succeeded, failed e cancelled.

Não há corpo. Listagens aceitam page e limit. Substitua {id}, quando presente, pelo UUID do recurso.

Resposta de sucesso

{
  "data": {
    "id": "00000000-0000-4000-8000-000000000001",
    "status": "succeeded",
    "attempts": [
      {
        "attempt": 1,
        "http_status": 200,
        "duration_ms": 130,
        "error_code": null
      }
    ],
    "payload": {
      "id": "00000000-0000-4000-8000-000000000001",
      "type": "payment.completed",
      "environment": "sandbox",
      "data": {
        "id": "00000000-0000-4000-8000-000000000001",
        "status": "completed",
        "amount_cents": 2500
      }
    }
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X GET "$LOOPPAY_URL/api/v1/webhook-deliveries/00000000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY"

Webhooks

Reprocessar entrega falha

POST/api/v1/webhook-deliveries/{id}/retrywebhooks:write

Somente failed, destino ativo e no máximo 3 reprocessamentos manuais. Enfileira novo ciclo de até 8 tentativas. O event_id continua o mesmo: deduplique no receptor. Envie {}.

Envie um objeto JSON. Use a mesma chave de idempotência ao repetir esta operação.

Resposta de sucesso

{
  "data": {
    "queued": true
  },
  "requestId": "UUID-DA-REQUISICAO"
}

Exemplo · cURL

curl -X POST "$LOOPPAY_URL/api/v1/webhook-deliveries/00000000-0000-4000-8000-000000000001/retry" \
  -H "Authorization: Bearer $LOOPPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: UUID-UNICO-PARA-ESTA-OPERACAO" \
  -d '{}'

Use uma chave de idempotência UUID real. Nos exemplos, gere uma chave uma única vez e preserve-a para eventuais novas tentativas.