Skip to main content
Pagamentos com cartão são processados na Stripe Connect (subconta Express vinculada à conta PJ). A GoatPay cobra taxa de plataforma via application_fee na Stripe — padrão 4,99% + US$ 0,20 (fixo convertido para BRL; taxa configurável por merchant). Base URL: https://api.goatpay.com.br/v1

​
Quando usar cada fluxo

CenárioAbordagem
Checkout único pela API (sem página GoatPay)POST /v1/card/checkout
Página de pagamento + PIX/boleto/cripto/cartãoLinks de pagamento com allowedMethods incluindo CARD
Primeira vez / cadastro incompletoPOST /v1/stripe/onboarding-link

​
Pré-requisitos

1

Conta PJ verificada

Cartão Connect exige Conta Padrão PJ com verificação aprovada. Contas PF ou trilho incompatível recebem 403.
2

API key com permissões

Habilite na chave: stripe/onboarding, card/checkout, card/get e, se for estornar, payments/refund.
3

Onboarding Stripe

Gere o link de cadastro e conclua o formulário Stripe até cobranças e repasses estarem habilitados.
4

Primeira cobrança

Redirecione o cliente para checkoutUrl (checkout avulso) ou use o fluxo de link.

​
Status exigidos antes de cobrar

FlagSignificado
charges_enabledPode criar checkouts e receber pagamentos
payouts_enabledRepasse para conta bancária do merchant na Stripe
Requisitos past_due vaziosSem pendências críticas no cadastro
Se algum item falhar, a API retorna 403 com mensagem orientando atualizar em Conta → Empresa → Cartão no dashboard.

​
Taxas e coverFee

CampoComportamento
coverFee: false (padrão)amount é o valor bruto cobrado no cartão; taxa GoatPay descontada do líquido
coverFee: trueamount é o líquido desejado; a taxa é calculada e somada ao valor do checkout
Taxa padrão: 4,99% do valor bruto + US$ 0,20 convertidos para reais (câmbio configurável no servidor). O valor exato de feeAmount e netAmount aparece na transação e nos webhooks após confirmação. Valor mínimo no checkout avulso: R$ 5,00.

​
Fluxo — checkout avulso

  1. Onboarding (uma vez ou quando o Stripe pedir atualização).
  2. Checkout com amount, description e URLs de retorno opcionais.
  3. Redirecione para checkoutUrl.
  4. Confirme com webhook payment.paid ou GET /v1/card/get/:id.

​
Rotas da API

MétodoRotaPermissãoDocumentação
POST/v1/stripe/onboarding-linkstripe/onboardingOnboarding
POST/v1/card/checkoutcard/checkoutCheckout
GET/v1/card/get/:idcard/getConsultar
POST/v1/payments/:id/refundpayments/refundEstorno

​
Webhooks recomendados

EventoUso
payment.paidCheckout avulso (card/checkout) — transação CARD_CREDIT_IN confirmada
payment.failedPagamento recusado ou sessão expirada
payment_link.paidPagamento via link de pagamento com method: CARD
Configure em Webhooks. Endpoints criados pela mesma API key recebem eventos das cobranças criadas com essa chave.

​
Estorno

POST /v1/payments/:id/refund estorna transações concluídas de cartão (transactionId retornado no checkout). Valor parcial opcional no body; omita amount para estorno integral do líquido. Somente transações com provider Stripe e status COMPLETED são elegíveis.

​
Liquidação e saldo

Depósitos de cartão podem ficar em pendente no saldo GoatPay até o prazo de liquidação (reserva de risco configurável). Consulte saldo em GET /v1/account/balance e extrato em transações.

​
Erros comuns

HTTPCausa típica
403Onboarding incompleto, cobranças/repasse desabilitados ou requisitos Stripe em atraso
400Valor abaixo do mínimo, transação não encontrada ou já estornada
401API key inválida ou ausente
Detalhes de códigos: Erros e códigos.

Criar checkout

POST /v1/card/checkout

Links + cartão

Vários métodos no mesmo link