Skip to main content
Cobranças comerciais na Conta Padrão (trilho PADRAO), para contas PF ou PJ verificadas. Use chave gp_live_... com as permissões abaixo.

​
Base URL e autenticação

https://api.goatpay.com.br/v1

curl 'https://api.goatpay.com.br/v1/billings/list' \
  -H 'X-API-Key: gp_live_SUA_CHAVE'
O trilho PADRAO vem da API key, não do body. Respostas seguem o envelope padrão.

​
Módulos

ProdutoPrefixo /v1Seção
Cobrança avulsa/billings/*Cobranças avulsas — boleto, cartão e PIX
Assinatura/subscriptions/*Assinaturas
Bureau de crédito/serasa/*Bureau de crédito — negativação e relatórios
Cobrança avulsa ≠ assinatura: POST /billings/create gera um pagamento. POST /subscriptions/create cria recorrência com ciclo fixo.

​
Permissões na API key

Ative na criação da chave (dashboard → Integrações):
GrupoPermissões
Cobrançasbillings/create, get, list, refund, tokenize
Assinaturassubscriptions/create, get, list, cancel
Bureau de créditoserasa/dunnings/*, serasa/reports/*
Lista completa: Permissões · Mapa geral: Rotas da API.

​
PIX: receber vs cobrar

CasoRotaQuando usar
QR PIX direto (receber)POST /payment-pix/createCheckout rápido, links, e-commerce — guia PIX
PIX em cobrança comercialPOST /billings/create com method: "PIX"Boleto/cartão/PIX no mesmo módulo de cobranças comerciais

​
Fluxo típico — cobrança avulsa

  1. Cadastre o pagador em /customers/* ou envie customer inline no create.
  2. POST /v1/billings/create com method, amount e customer.
  3. Entregue boleto (bankSlipUrl, digitableLine), PIX (pixCopyPaste) ou confirme cartão.
  4. Acompanhe com GET /v1/billings/get/{id} ou webhooks.
  5. Estorne com POST /v1/billings/refund se necessário.

​
Fluxo típico — assinatura

  1. POST /v1/subscriptions/create com method, amount, cycle, nextDueDate e customer.
  2. Consulte com GET /v1/subscriptions/get/{id} ou liste com filtros.
  3. Cancele a recorrência com POST /v1/subscriptions/cancel/{id}.

​
Clientes

Base de pagadores usada em cobranças e assinaturas. As mesmas rotas servem a Loja.

​
Rotas

MétodoRotaPermissãoDocumentação
POST/v1/customers/createcustomers/createCriar
GET/v1/customers/get/:idcustomers/getConsultar
GET/v1/customers/listcustomers/listListar
PATCH/v1/customers/update/:idcustomers/updateAtualizar
DELETE/v1/customers/delete/:idcustomers/deleteExcluir
No billings/create e subscriptions/create, o objeto customer aceita name, taxId (CPF ou CNPJ), email, phone e id opcional (referência interna).

​
Cobranças avulsas

Pagamento único: boleto, cartão ou PIX comercial.

​
Rotas

MétodoRotaPermissãoDocumentação
POST/v1/billings/createbillings/createCriar
POST/v1/billings/tokenize-cardbillings/tokenizeTokenizar cartão
GET/v1/billings/get/:idbillings/getConsultar
GET/v1/billings/listbillings/listListar
POST/v1/billings/refundbillings/refundEstornar

​
Métodos (method)

ValorDescrição
BOLETOBoleto bancário com PDF e linha digitável
CARD_CREDITCartão de crédito — veja Cartão
CARD_DEBITCartão de débito
CARD_VOUCHERVoucher / benefício
PIXPIX via rota comercial (distinto de payment-pix)

​
Cartão

Fluxo recomendado:
  1. Primeira cobrança: POST /billings/create com method: "CARD_CREDIT", creditCard, creditCardHolderInfo e remoteIp (IP do pagador).
  2. Resposta: guarde data.charge.creditCardToken — é o token para reutilizar.
  3. Próximas cobranças: envie cardToken + remoteIp (sem PAN/CVV).
  4. Alternativa: POST /billings/tokenize-card gera o token sem cobrar; depois use cardToken no create.
Campos de cartão: creditCard (dados do cartão), creditCardHolderInfo (titular). O creditCardToken retornado é reutilizado como cardToken nas próximas cobranças.
remoteIp deve ser o IP do comprador, não do seu servidor. Nunca armazene número completo do cartão ou CVV após a transação.

​
Status da cobrança

StatusSignificado
PENDINGAguardando pagamento
CONFIRMEDConfirmado (cartão)
RECEIVEDPago
OVERDUEVencido
CANCELEDCancelado
REFUNDEDEstornado
FAILEDFalha
Detalhes dos campos de resposta: Consultar cobrança.

​
Assinaturas

Cobrança recorrente com ciclo fixo.

​
Rotas

MétodoRotaPermissãoDocumentação
POST/v1/subscriptions/createsubscriptions/createCriar
GET/v1/subscriptions/listsubscriptions/listListar
GET/v1/subscriptions/get/:idsubscriptions/getConsultar
POST/v1/subscriptions/cancel/:idsubscriptions/cancelCancelar

​
Ciclos (cycle)

WEEKLY, BIWEEKLY, MONTHLY, BIMONTHLY, QUARTERLY, SEMIANNUALLY, YEARLY.

​
Métodos

BOLETO, CARD_CREDIT ou PIX — para cartão use o mesmo fluxo de Cartão (creditCard + titular na primeira vez, ou cardToken depois).

​
Bureau de crédito

Negativação de inadimplentes e consultas de crédito via bureau integrado à GoatPay. Exige conta verificada no trilho PADRAO.

​
Negativação (dunnings)

Fluxo típico:
  1. Tenha uma cobrança em atraso (billings) com o devedor cadastrado.
  2. Opcional: Simular com ?payment={id} para verificar elegibilidade.
  3. Solicitar negativação via multipart/form-data (dados do devedor, endereço e documentos).
  4. Acompanhe com Listar ou Consultar.
MétodoRotaDocumentação
POST/serasa/dunnings/createCriar
GET/serasa/dunnings/listListar
GET/serasa/dunnings/get/:idConsultar
GET/serasa/dunnings/simulateSimular
Taxa de referência para negativação: R$ 12,90 por solicitação. Campos principais no create: payment (ID da cobrança), type=CREDIT_BUREAU, dados do devedor e documents (arquivo).

​
Relatórios de crédito

Consulta de crédito por CPF/CNPJ vinculada a um cliente cadastrado.
MétodoRotaDocumentação
POST/serasa/reports/createCriar
GET/serasa/reports/listListar
GET/serasa/reports/get/:idConsultar
Envie customer (ID do cliente em POST /customers/create) e cpfCnpj em POST /serasa/reports/create. Taxa de referência: R$ 19,90.

​
Webhooks

Confirme pagamentos sem polling. Eventos relevantes: payment.created, payment.paid, payment.refunded. Veja Webhooks.

​
Próximos passos

Criar cobrança

Boleto, cartão ou PIX (pagamento único).

Listar assinaturas

Paginação e filtros por status.

Criar assinatura

Plano recorrente com ciclo fixo.

Negativar inadimplente

Bureau de crédito.

Consulta de crédito

Relatório de crédito.