> ## Documentation Index > Fetch the complete documentation index at: https://docs.pilotstatus.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Recarga da carteira (cartão ou Pix) / adicionar cartão > Recarrega a carteira pré-paga ou salva um cartão — nada é cobrado até uma pessoa pagar. purpose:"wallet_topup" (exige amount > 0, na moeda da conta) com method "card" (padrão) devolve uma `url` hospedada do Stripe; com method "pix" (só BRL) devolve `orderId` e `pix { transactionId, copyPaste, qrCode, expiresAt }` — o Pix expira em 1 hora. Acompanhe o pedido com `GET /v1/billing/topups/{orderId}`. purpose:"add_card" devolve uma página hospedada para salvar um cartão no workspace, que passa a cobrir a carteira em toda cobrança. Ação de conta: requer key escopada a TENANT (403 NUMBER_SCOPE_NOT_ALLOWED para key de número); só Proprietário com chave de conta ou token OAuth. **Requer uma chave com escopo de tenant** — uma chave de workspace, ou uma chave de conta com `x-workspace-id`. Os erros são bilíngues (`English | Português`) desde 29/10/2026: `INVALID_PURPOSE`, `INVALID_AMOUNT`, `NO_BILLING_EMAIL` (400) e `CHECKOUT_FAILED` (500) eram só em inglês. Os códigos e os status não mudaram — decida pelo `code`. ## OpenAPI ````yaml openapi.pt.json POST /v1/billing/checkout openapi: 3.1.0 info: title: API Pilot Status version: 1.0.0 license: name: Pilot Status Terms of Service url: https://pilotstatus.com.br/terms description: >- API REST pública do Pilot Status. Autentique com o header `x-api-key: ps_...` (ou `x-api-key-id`). Base URL: https://pilotstatus.com.br servers: - url: https://pilotstatus.com.br security: - apiKey: [] - apiKeyId: [] paths: /v1/billing/checkout: post: tags: - Billing summary: Recarga da carteira (cartão ou Pix) / adicionar cartão description: >- Recarrega a carteira pré-paga ou salva um cartão — nada é cobrado até uma pessoa pagar. purpose:"wallet_topup" (exige amount > 0, na moeda da conta) com method "card" (padrão) devolve uma `url` hospedada do Stripe; com method "pix" (só BRL) devolve `orderId` e `pix { transactionId, copyPaste, qrCode, expiresAt }` — o Pix expira em 1 hora. Acompanhe o pedido com `GET /v1/billing/topups/{orderId}`. purpose:"add_card" devolve uma página hospedada para salvar um cartão no workspace, que passa a cobrir a carteira em toda cobrança. Ação de conta: requer key escopada a TENANT (403 NUMBER_SCOPE_NOT_ALLOWED para key de número); só Proprietário com chave de conta ou token OAuth. **Requer uma chave com escopo de tenant** — uma chave de workspace, ou uma chave de conta com `x-workspace-id`. Os erros são bilíngues (`English | Português`) desde 29/10/2026: `INVALID_PURPOSE`, `INVALID_AMOUNT`, `NO_BILLING_EMAIL` (400) e `CHECKOUT_FAILED` (500) eram só em inglês. Os códigos e os status não mudaram — decida pelo `code`. operationId: post_billing_checkout parameters: - name: x-workspace-id in: header required: false schema: type: string description: >- Só com chave de conta (`ps_account_`): o workspace em que agir, obtido em `GET /v1/workspaces`. Sem ele, uma chave de conta recebe `400 WORKSPACE_ID_REQUIRED`. example: cmh2a9z8y0002ws8example1q requestBody: required: true content: application/json: schema: type: object properties: purpose: type: string description: Finalidade da página de checkout. example: wallet_topup amount: type: string description: >- Valor a creditar na carteira, na moeda da conta (obrigatório para wallet_topup). example: '50' successUrl: type: string description: URL de redirecionamento após o sucesso. example: https://app.acme.com/billing/ok cancelUrl: type: string description: URL de redirecionamento se cancelar. example: https://app.acme.com/billing method: type: string enum: - card - pix description: >- Só para `wallet_topup`. `card` (padrão) devolve uma página hospedada do Stripe; `pix` (só workspaces em BRL; senão `400 PIX_NOT_ELIGIBLE`) devolve um código Pix copia e cola e um QR code (`data:image/png;base64,…`). `successUrl`/`cancelUrl` com `pix`, ou `method` com `add_card` → `400 FIELD_NOT_APPLICABLE`. example: pix required: - purpose responses: '200': description: Checkout criado content: application/json: examples: card: summary: Recarga com cartão (página hospedada) value: url: https://checkout.stripe.com/c/pay/cs_live_... purpose: wallet_topup method: card orderId: cmh2b5m2p0002to8example6r amount: 50 currency: BRL pix: summary: Recarga com Pix value: 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' addCard: summary: Salvar cartão value: url: https://checkout.stripe.com/c/pay/cs_live_... purpose: add_card '400': description: >- Payload ou parâmetros inválidos — ou `INVALID_BODY` quando o corpo não é um JSON válido content: application/json: schema: type: object properties: error: type: string code: type: string examples: validation: summary: Erro de validação value: error: Validation error invalidBody: summary: Corpo não é um JSON válido value: error: >- The request body is not valid JSON | O corpo da requisição não é um JSON válido code: INVALID_BODY invalidPurpose: summary: purpose desconhecido value: error: >- purpose must be 'wallet_topup' or 'add_card'. | purpose deve ser 'wallet_topup' ou 'add_card'. code: INVALID_PURPOSE invalidAmount: summary: amount não positivo value: error: >- amount must be a positive number. | amount deve ser um número positivo. code: INVALID_AMOUNT noBillingEmail: summary: Sem e-mail de cobrança (cartão) value: error: >- This workspace has no billing e-mail on file. | Este workspace não tem e-mail de cobrança cadastrado. code: NO_BILLING_EMAIL '401': description: Header `x-api-key` / `x-api-key-id` ausente ou inválido content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Unauthorized '403': description: Chave com escopo de número usada em endpoint exclusivo de tenant content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Number-scoped keys cannot call tenant endpoints code: NUMBER_SCOPE_NOT_ALLOWED '429': description: Limite de taxa excedido content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Too many requests '500': description: '`CHECKOUT_FAILED` — falha inesperada ao criar o checkout' content: application/json: schema: type: object properties: error: type: string code: type: string example: error: >- Failed to create the checkout session. | Não foi possível criar a sessão de pagamento. code: CHECKOUT_FAILED components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: Sua chave de API ps_ apiKeyId: type: apiKey in: header name: x-api-key-id description: Id da chave de API (alternativa ao x-api-key) ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.