Guia rápido

Toda chave de API do FeitPay é uma chave live e todo pagamento é real. Você pode se cadastrar, configurar sua organização e enviar a verificação da sua empresa imediatamente. Chaves de API live, intenções de pagamento, sessões de checkout e saques ficam disponíveis quando sua conta for ativada: os pagamentos são ativados após a verificação e aprovação da sua conta.

Todos os exemplos usam marcadores como gp_live_YOUR_KEY e store_YOUR_STORE_ID — nunca cole segredos reais no código.

Pagamentos exigem uma conta ativada

Os passos 4 a 9 só funcionam depois que a sua conta é ativada. Até lá a API responde com feature_unavailable_error — por exemplo live_keys_disabled (conta ainda não ativada) ao tentar criar uma chave live. Todo pagamento é real desde o primeiro, então comece com um valor pequeno.

1. Crie uma conta. Cadastre-se em https://app.feitpay.com/auth/sign-up e confirme seu e-mail; depois crie uma organização e uma loja. O checklist de configuração mostra exatamente o que bloqueia o próximo passo.

2. Envie a verificação da sua empresa. Em Organização → Conformidade, preencha a solicitação de lojista (KYB) e envie. Os operadores do FeitPay a revisam manualmente; enviar não é uma aprovação, e nada é aprovado automaticamente.

3. Aguarde a ativação. O FeitPay ativa a sua conta para pagamentos live depois que a sua verificação é aprovada e os demais requisitos para pagamentos live são atendidos (veja a Situação regulatória). O checklist de configuração marca a etapa do modo live como concluída quando a sua conta é ativada.

4. Crie uma chave de API live em Integração → Chaves de API com os escopos payments:write e payments:read. O segredo (gp_live_…) é exibido uma única vez LIVE · após ativação da conta. Mantenha-o no seu servidor.

5. Cadastre um endpoint de webhook em Integração → Webhooks ou pela API. Guarde o segredo de assinatura whsec_…; ele é exibido uma única vez. Cadastre-o depois do passo 3: endpoints pertencem a um ambiente, e os eventos live só são entregues a endpoints cadastrados no modo live.

6. Crie uma intenção de pagamento.

   POST/v1/payment-intentslive · após ativação da conta
   curl

   curl -X POST https://api.feitpay.com/v1/payment-intents \
     -H "Authorization: Bearer gp_live_YOUR_KEY" \
     -H "Idempotency-Key: order-123" \
     -H "Content-Type: application/json" \
     -d '{
       "store_id": "store_YOUR_STORE_ID",
       "amount": "59.90",
       "currency": "EUR",
       "merchant_order_id": "order-123",
       "return_url": "https://merchant.example/thank-you"
     }'

   TypeScript

   import { FeitPay } from '@feitpay/sdk';
   
   const gp = new FeitPay({ apiKey: process.env.FEITPAY_API_KEY!, baseUrl: 'https://api.feitpay.com' });
   
   const intent = await gp.paymentIntents.create(
     {
       store_id: 'store_YOUR_STORE_ID',
       amount: '59.90',
       currency: 'EUR',
       merchant_order_id: 'order-123',
       return_url: 'https://merchant.example/thank-you',
     },
     { idempotencyKey: 'order-123' },
   );
   console.log(intent.status, intent.checkout_url);

   Go

   client, err := feitpay.New(os.Getenv("FEITPAY_API_KEY"), feitpay.WithBaseURL("https://api.feitpay.com"))
   if err != nil {
     log.Fatal(err)
   }
   intent, err := client.PaymentIntents.Create(ctx, &feitpay.PaymentIntentCreateParams{
     StoreID:         "store_YOUR_STORE_ID",
     Amount:          "59.90",
     Currency:        "EUR",
     MerchantOrderID: "order-123",
     ReturnURL:       "https://merchant.example/thank-you",
     IdempotencyKey:  "order-123",
   })

   Python

   import os
   from feitpay import FeitPay
   
   gp = FeitPay(api_key=os.environ["FEITPAY_API_KEY"], base_url="https://api.feitpay.com")
   intent = gp.payment_intents.create(
       store_id="store_YOUR_STORE_ID",
       amount="59.90",
       currency="EUR",
       merchant_order_id="order-123",
       return_url="https://merchant.example/thank-you",
       idempotency_key="order-123",
   )
   print(intent["status"], intent["checkout_url"])

   A resposta é um payment_intent com status: "created", livemode: true, um expires_at, uma checkout_url hospedada em https://checkout.feitpay.com e um objeto processor (name: "bitcart", custodial: true). Repetir a mesma requisição com a mesma Idempotency-Key retorna a mesma intenção. Não envie allowed_networks: pagamentos live oferecem todos os ativos que a plataforma aceita, e o campo é recusado com allowed_networks_unsupported.

7. O cliente paga no checkout hospedado. Envie o cliente para a checkout_url. O checkout abre uma fatura na conta Bitcart da plataforma e mostra, para cada ativo aceito, um endereço, o valor exato calculado com a taxa de câmbio da Bitcart e um QR code. O cliente paga para a carteira do FeitPay; o valor é creditado ao seu saldo em custódia quando o pagamento é concluído.

8. Acompanhe a máquina de estados. A intenção passa por awaiting_payment → detected → confirming → confirmed conforme a Bitcart informa a fatura como paga, confirmada e concluída. O checkout, o painel e o seu endpoint de webhook veem os mesmos estados.

9. Verifique o webhook e entregue o pedido. Seu endpoint recebe payment.confirmed. Verifique a assinatura sobre o corpo bruto (veja Verificar assinaturas de webhook), descarte duplicatas pelo event_id e só entregue quando data.fulfillable for true — confirmando com GET /v1/payment-intents/{id} antes de qualquer ação irreversível.

Saque do seu saldo

Pagamentos confirmados são creditados ao seu saldo em custódia (GET /v1/balances). Para sacar, adicione um endereço em Finanças → Saques → Endereços de saque (utilizável após um período de espera), solicite o saque e peça a um segundo membro da sua organização que o aprove (ativado por padrão). Um operador do FeitPay revisa todo saque antes de a carteira quente da plataforma enviá-lo. Os saques são ativados separadamente dos pagamentos live; até lá, uma solicitação de saque é recusada com payouts_unavailable (conta ainda não ativada para saques).

Execute os exemplos

O repositório inclui receptores executáveis que verificam assinaturas e processam cada evento uma única vez:

Exemplo	Porta	Execução
examples/node-saas	4400	FEITPAY_WEBHOOK_SECRET=whsec_… pnpm --filter @feitpay/example-node-saas start
examples/go-webhook	4401	cd examples/go-webhook && FEITPAY_WEBHOOK_SECRET=whsec_… go run .
examples/python-shop	4402	FEITPAY_WEBHOOK_SECRET=whsec_… python examples/python-shop/shop.py

Próximos passos

• Entenda cada status na máquina de estados.
• Veja o que o cliente vê no checkout hospedado.
• Leia o modelo de segurança antes de desenhar sua integração.
• Leia a situação regulatória para entender o que a ativação da sua conta envolve.