​

Carteira e cartão pela API

​

Credenciais e permissões

• Uma credencial de nível de workspace: uma chave de workspace, ou uma chave de conta com x-workspace-id. Uma chave de número, ou um token limitado a alguns números, recebe 403 NUMBER_SCOPE_NOT_ALLOWED.
• Papel, com uma chave de conta ou um token OAuth/MCP: recarregar e salvar cartão são ações do Proprietário; ler o status de uma recarga (GET /v1/billing/topups/{id}) exige Proprietário ou Administrador. Um papel abaixo disso recebe 403 PERMISSION_DENIED. Uma chave de workspace não tem usuário, então nenhum papel se aplica.
• Moeda: o valor é sempre na moeda do workspace (BRL ou USD). Não dá para escolher por requisição.

​

Recarga com Pix

curl -X POST "https://pilotstatus.com.br/v1/billing/checkout" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_workspace_your_key" \
  -d '{ "purpose": "wallet_topup", "method": "pix", "amount": 100 }'

{
  "purpose": "wallet_topup",
  "method": "pix",
  "orderId": "cmh2b4k1n0001to8example2p",
  "status": "pending",
  "amount": 100,
  "currency": "BRL",
  "pix": {
    "transactionId": "pdev_tx_8f2a1c",
    "copyPaste": "00020126580014br.gov.bcb.pix0136…6304ABCD",
    "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…",
    "expiresAt": "2026-10-28T11:15:00.000Z"
  }
}

• Mostre pix.copyPaste (o código copia e cola) e/ou pix.qrCode (a imagem do QR code como URI data:image/png;base64,…, pronta para um <img src>; pode vir null) para quem vai pagar. Um Pix expira em 1 hora (pix.expiresAt).
• Guarde o orderId: é com ele que você acompanha o pagamento em GET /v1/billing/topups/{id} e é ele que o webhook wallet.topup_paid informa.
• Um workspace em USD recebe 400 PIX_NOT_ELIGIBLE. Use cartão.
• successUrl e cancelUrl não fazem sentido num Pix: enviá-los dá 400 FIELD_NOT_APPLICABLE.

​

Recarga ou cartão numa página hospedada do Stripe

curl -X POST "https://pilotstatus.com.br/v1/billing/checkout" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_workspace_your_key" \
  -d '{
    "purpose": "wallet_topup",
    "amount": 50,
    "successUrl": "https://app.example.com/billing?paid=1",
    "cancelUrl": "https://app.example.com/billing"
  }'

{
  "url": "https://checkout.stripe.com/c/pay/cs_live_…",
  "purpose": "wallet_topup",
  "method": "card",
  "orderId": "cmh2b5m2p0002to8example6r",
  "amount": 50,
  "currency": "BRL"
}

​

Acompanhar uma recarga

{
  "topup": {
    "id": "cmh2b4k1n0001to8example2p",
    "status": "paid",
    "amount": 100,
    "currency": "BRL",
    "method": "pix",
    "provider": "PAGUE_DEV",
    "createdAt": "2026-10-28T10:15:00.000Z",
    "paidAt": "2026-10-28T10:17:42.000Z",
    "expiresAt": "2026-10-28T11:15:00.000Z"
  }
}

• Só lê. Não chama nenhum provedor de pagamento, então consultar repetidamente é barato. O pedido passa a paid quando o provedor de pagamento nos confirma o pagamento.
• Prefira o webhook a consultar em loop. O wallet.topup_paid chega uma vez por pedido creditado. Ele só é enviado depois que o pedido é concluído, então, quando chega, este endpoint já responde paid.
• Um id de outro workspace recebe o mesmo 404 TOPUP_NOT_FOUND de um id que não existe.

​

Cartão na sua própria página (Stripe Elements)

• respondem com Cache-Control: no-store — um clientSecret permite a quem o tiver confirmar o intent, então não o guarde em cache nem em log;
• devolvem a publishableKey com que carregar o Stripe.js, então você não precisa de uma conta Stripe própria;
• respondem 503 PAYMENTS_NOT_CONFIGURED quando pagamentos com cartão não estão disponíveis do nosso lado. Ofereça Pix (BRL) ou tente de novo mais tarde.

​

Salvar um cartão

{
  "clientSecret": "seti_1QabcDEF_secret_xyz",
  "setupIntentId": "seti_1QabcDEF",
  "publishableKey": "pk_live_…"
}

{
  "setupIntentId": "seti_1QabcDEF",
  "status": "succeeded",
  "saved": true,
  "card": { "brand": "visa", "last4": "4242", "expMonth": 12, "expYear": 2030 }
}

• O sync lê o intent no Stripe; ele nunca confia na sua página. Quando o Stripe diz succeeded, o cartão passa a ser o cartão salvo do workspace, substituindo o anterior.
• Ainda não concluído (processing, requires_action, …): saved: false, card: null e o status do Stripe. Chame de novo mais tarde, ou conte com o nosso lado: o Stripe também nos avisa, e o cartão é salvo nesse momento.
• Idempotente. Chamar de novo, ou concorrer com o nosso próprio aviso do Stripe, salva o cartão uma vez só.
• Um id que não é seti_… → 400 INVALID_SETUP_INTENT_ID. Um id que não criamos para este workspace → 404 SETUP_INTENT_NOT_FOUND.

​

Recarga com cartão

curl -X POST "https://pilotstatus.com.br/v1/billing/payment-intents" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_workspace_your_key" \
  -H "Idempotency-Key: topup-customer-42-2026-10-28" \
  -d '{ "purpose": "wallet_topup", "amount": 150, "saveCard": true }'

{
  "clientSecret": "pi_3QabcDEF_secret_xyz",
  "paymentIntentId": "pi_3QabcDEF",
  "orderId": "cmh2b7q4s0003to8example8t",
  "amount": 150,
  "currency": "BRL",
  "publishableKey": "pk_live_…"
}

{
  "paymentIntentId": "pi_3QabcDEF",
  "status": "succeeded",
  "amount": 150,
  "currency": "BRL",
  "orderId": "cmh2b7q4s0003to8example8t",
  "orderStatus": "COMPLETED",
  "credited": true,
  "balance": 212.4,
  "cardSaved": true
}

• O sync nunca cobra. Ele não é o /confirm do Stripe: só reconcilia o que o Stripe já decidiu. A carteira é creditada exatamente uma vez, pelo sync ou pelo nosso aviso do Stripe, o que chegar primeiro.
• Um id que não é pi_… → 400 INVALID_PAYMENT_INTENT_ID. Um id que não criamos como recarga deste workspace → 404 PAYMENT_INTENT_NOT_FOUND.
• O orderId funciona em GET /v1/billing/topups/{id} como o de qualquer outra recarga.

​

Idempotency-Key

• Ausente: toda chamada cria um novo pedido e um novo payment intent.
• Mesma chave e mesmo corpo em até 24 horas: você recebe o mesmo orderId, paymentIntentId e clientSecret, com o header Idempotent-Replayed: true. Nada novo é criado.
• Mesma chave, corpo diferente: 409 IDEMPOTENCY_KEY_REUSED. Use uma chave nova.
• Mesma chave enquanto a primeira chamada ainda está rodando: 409 IDEMPOTENCY_KEY_IN_USE. Tente de novo em instantes.
• As chaves são por workspace. Uma chamada que falhou na validação, ou falhou depois, não gasta a chave.

​

Erros

​

Revendedores e o cartão compartilhado