Skip to main content
Recursos da loja no dashboard GoatPay, expostos na API pública v1 com chave gp_live_....

​
Base URL e autenticação

Todas as rotas abaixo usam o prefixo:
O trilho PADRAO vem da API key, não do body. Respostas seguem o envelope padrão.

​
Módulos

​
Permissões na API key

Ative na criação da chave (dashboard → Integrações): Lista completa: Permissões · Mapa geral: Rotas da API.

​
Fluxo típico de venda

  1. Cadastre produto (opcional) e link com allowedMethods (PIX, CRYPTO).
  2. Opcional: POST /v1/coupons/validate e depois couponCode no checkout.
  3. POST /v1/payment-links/checkout → redirecione o cliente para payCheckoutUrl.
  4. Confirme com webhook payment_link.paid ou GET /v1/payment-links/sessions/get/:sessionId.

​
Clientes

Gerencie a base de clientes vinculada ao trilho da sua API key. Os mesmos pagadores servem cobranças e assinaturas.

​
Rotas

​
Listagem

GET /v1/customers/list aceita:
  • page, pageSize (máx. 100)
  • search — nome, e-mail ou documento
  • status — Ativo, Inativo, Bloqueado ou active / inactive / blocked
Resposta paginada: items, page, pageSize, total, pages.

​
Campos do cliente

​
Checkout automático

Clientes também são criados ou atualizados no checkout de links quando o customerMode do link exige cadastro. Você pode manter o CRM sincronizado via API ou confiar no fluxo do link.

​
Produtos

Catálogo e entregas digitais. Base: https://api.goatpay.com.br/v1/products/*

​
Rotas

​
Corpo de criação

​
Tipos de entrega (deliveries[].type)

Upload de imagem e arquivos em lote permanece no dashboard (multipart). A API cobre metadados, preço, status e regras de entrega.
Passe productIds ao criar ou atualizar um link de pagamento.

​
Cupons

Cupons de desconto para links. Base: https://api.goatpay.com.br/v1/coupons/*

​
Rotas

​
Tipos de desconto

​
Restrições

  • productIds — cupom só vale para produtos listados
  • paymentLinkIds — cupom só vale para links listados
  • maxUses, expiresAt — limite de uso e validade

​
Fluxo no checkout

1

Validar

POST /v1/coupons/validate com code, amount, paymentLinkId (e productId se restrito).
2

Checkout

POST /v1/payment-links/checkout com couponCode igual ao código validado.
3

Confirmar

Webhook payment_link.paid ou sessão.
Checkouts hospedados na GoatPay — PIX e cripto. Base: https://api.goatpay.com.br/v1/payment-links/* Links permitem que seu site ou app crie cobranças pela API e redirecione o cliente para pay.goatpay.com.br.

​
Rotas

​
Pré-requisitos

Conta verificada; métodos PIX e/ou CRYPTO habilitados no trilho PADRÃO da API key.

​
Fluxo recomendado

1

1. Criar o link

POST /v1/payment-links/create com allowedMethods, valor fixo (fixedAmount) ou aberto.
2

2. Iniciar checkout

POST /v1/payment-links/checkout com linkId, method e dados do pagador.
3

3. Pagar

Redirecione para payCheckoutUrl ou a página payPageUrl do link.
4

4. Confirmar

Webhook payment_link.paid ou GET /v1/payment-links/sessions/get/:sessionId.

​
Idempotência

Envie Idempotency-Key em POST /v1/payment-links/checkout para evitar cobranças duplicadas em retentativas.

​
Referência externa

externalReference no checkout correlaciona com seu pedido. Aparece na transação e no webhook payment_link.paid.

Criar cliente

POST /v1/customers/create

Criar link

POST /v1/payment-links/create