> ## 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. # Iniciar uma recarga com cartão (Stripe Elements) > Cria um pedido de recarga PENDENTE e um PaymentIntent de cartão para o `amount` (na moeda do workspace, arredondado para centavos), para um formulário de cartão na sua própria página. Chame `stripe.confirmPayment()` com o `clientSecret` e depois `POST /v1/billing/payment-intents/{id}/sync`. A carteira é creditada uma única vez, pelo `sync` ou pelo nosso webhook do Stripe. `saveCard: true` também salva o cartão. `Idempotency-Key` opcional: mesma chave e mesmo corpo em 24 h → o mesmo intent, com `Idempotent-Replayed: true`; mesma chave, outro corpo → `409 IDEMPOTENCY_KEY_REUSED`; ainda em processamento → `409 IDEMPOTENCY_KEY_IN_USE`. Só Proprietário (`billing:wallet:topup`). Os dados do cartão vão do navegador de quem paga direto para o Stripe (Payment Element) e nunca chegam à Pilot Status. O `clientSecret` permite a quem o tiver confirmar o intent: não guarde em cache nem em log. Enviado com `Cache-Control: no-store`. **Requer uma chave com escopo de tenant** — uma chave de workspace, ou uma chave de conta com `x-workspace-id`. > [!WARNING] > > Nada é cobrado aqui: o pagamento acontece quando o Stripe.js confirma na sua página. Veja [Checkout transparente](https://docs.pilotstatus.com.br/pt-BR/guides/transparent-checkout.md). ## OpenAPI ````yaml openapi.pt.json POST /v1/billing/payment-intents 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/payment-intents: post: tags: - Billing summary: Iniciar uma recarga com cartão (Stripe Elements) description: >- Cria um pedido de recarga PENDENTE e um PaymentIntent de cartão para o `amount` (na moeda do workspace, arredondado para centavos), para um formulário de cartão na sua própria página. Chame `stripe.confirmPayment()` com o `clientSecret` e depois `POST /v1/billing/payment-intents/{id}/sync`. A carteira é creditada uma única vez, pelo `sync` ou pelo nosso webhook do Stripe. `saveCard: true` também salva o cartão. `Idempotency-Key` opcional: mesma chave e mesmo corpo em 24 h → o mesmo intent, com `Idempotent-Replayed: true`; mesma chave, outro corpo → `409 IDEMPOTENCY_KEY_REUSED`; ainda em processamento → `409 IDEMPOTENCY_KEY_IN_USE`. Só Proprietário (`billing:wallet:topup`). Os dados do cartão vão do navegador de quem paga direto para o Stripe (Payment Element) e nunca chegam à Pilot Status. O `clientSecret` permite a quem o tiver confirmar o intent: não guarde em cache nem em log. Enviado com `Cache-Control: no-store`. **Requer uma chave com escopo de tenant** — uma chave de workspace, ou uma chave de conta com `x-workspace-id`. operationId: post_billing_payment_intents parameters: - name: Idempotency-Key in: header required: false schema: type: string maxLength: 255 description: Opcional. Até 255 caracteres, sem caracteres de controle. example: topup-customer-42-2026-10-28 - 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 additionalProperties: false properties: purpose: type: string enum: - wallet_topup description: Hoje, só `wallet_topup`. example: wallet_topup amount: type: number description: Positivo, na moeda do workspace. example: 150 saveCard: type: boolean description: >- Também salvar o cartão como cartão do workspace. Padrão `false`. example: true required: - purpose - amount responses: '200': description: O intent content: application/json: example: clientSecret: pi_3QabcDEF_secret_xyz paymentIntentId: pi_3QabcDEF orderId: cmh2b7q4s0003to8example8t amount: 150 currency: BRL publishableKey: pk_live_... headers: Cache-Control: schema: type: string example: no-store Idempotent-Replayed: schema: type: string description: '`true` numa repetição.' example: 'true' '400': description: >- `INVALID_BODY`, `UNKNOWN_FIELDS`, `INVALID_PURPOSE`, `INVALID_AMOUNT`, `INVALID_FIELD_TYPE`, `AMOUNT_TOO_SMALL` ou `IDEMPOTENCY_KEY_INVALID` content: application/json: schema: type: object properties: error: type: string code: type: string example: error: >- amount must be a positive number. | amount deve ser um número positivo. code: INVALID_AMOUNT '401': description: Chave de API ausente, inválida ou revogada content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Invalid API key '403': description: >- Chave com escopo de número (`NUMBER_SCOPE_NOT_ALLOWED`), papel do usuário sem permissão (`PERMISSION_DENIED`) ou chave de conta fora dos seus workspaces (`WORKSPACE_MEMBERSHIP_REQUIRED`) content: application/json: schema: type: object properties: error: type: string code: type: string example: error: This endpoint requires a tenant-scoped API key code: NUMBER_SCOPE_NOT_ALLOWED '409': description: '`IDEMPOTENCY_KEY_REUSED` ou `IDEMPOTENCY_KEY_IN_USE`' content: application/json: schema: type: object properties: error: type: string code: type: string example: error: >- This Idempotency-Key was already used with different parameters. Use a new key. | Esta Idempotency-Key já foi usada com outros parâmetros. Use uma nova chave. code: IDEMPOTENCY_KEY_REUSED '503': description: Pagamentos com cartão indisponíveis no momento content: application/json: schema: type: object properties: error: type: string code: type: string example: error: >- Card payments are not available right now. | Pagamentos com cartão não estão disponíveis no momento. code: PAYMENTS_NOT_CONFIGURED 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.