​

Wallet and card via API

​

Credentials and permissions

• A workspace-level credential: a workspace key, or an account key with x-workspace-id. A number key, or a token limited to some numbers, gets 403 NUMBER_SCOPE_NOT_ALLOWED.
• Role, with an account key or an OAuth/MCP token: topping up and saving a card are Owner actions; reading a top-up status (GET /v1/billing/topups/{id}) needs Owner or Admin. A lower role gets 403 PERMISSION_DENIED. A workspace key has no user, so no role applies.
• Currency: the amount is always in the workspace’s currency (BRL or USD). It cannot be chosen per request.

​

Top up with 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"
  }
}

• Show pix.copyPaste (the copy-and-paste code) and/or pix.qrCode (the QR code image as a data:image/png;base64,… URI, ready for an <img src>; it can be null) to whoever pays. A Pix expires in 1 hour (pix.expiresAt).
• Keep orderId: it is how you follow the payment with GET /v1/billing/topups/{id} and how the wallet.topup_paid webhook names it.
• A USD workspace gets 400 PIX_NOT_ELIGIBLE. Use a card.
• successUrl and cancelUrl have no meaning for a Pix: sending them gets 400 FIELD_NOT_APPLICABLE.

​

Top up or save a card on a hosted Stripe page

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"
}

​

Follow a top-up

{
  "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"
  }
}

• It only reads. It calls no payment provider, so polling it is cheap. The order turns paid when the payment provider confirms the payment to us.
• Prefer the webhook to polling. wallet.topup_paid arrives once per credited order. It is sent only after the order is completed, so when it arrives this endpoint already answers paid.
• An id from another workspace gets the same 404 TOPUP_NOT_FOUND as an id that does not exist.

​

Card on your own page (Stripe Elements)

• answer with Cache-Control: no-store — a clientSecret lets whoever holds it confirm the intent, so do not cache or log it;
• return the publishableKey to load Stripe.js with, so you do not need any Stripe account of your own;
• answer 503 PAYMENTS_NOT_CONFIGURED when card payments are not available on our side. Offer Pix (BRL) or try again later.

​

Save a card

{
  "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 }
}

• sync reads the intent from Stripe; it never trusts your page. When Stripe says succeeded, the card becomes the workspace’s saved card, replacing the previous one.
• Not succeeded yet (processing, requires_action, …): saved: false, card: null and Stripe’s status. Call again later, or rely on our side: Stripe also notifies us, and the card is saved then.
• Idempotent. Calling it again, or racing our own Stripe notification, saves the card once.
• An id that is not a seti_… → 400 INVALID_SETUP_INTENT_ID. An id we did not create for this workspace → 404 SETUP_INTENT_NOT_FOUND.

​

Top up with a card

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
}

• sync never charges. It is not Stripe’s /confirm: it only reconciles what Stripe already decided. The wallet is credited exactly once, by sync or by our Stripe notification, whichever comes first.
• An id that is not a pi_… → 400 INVALID_PAYMENT_INTENT_ID. An id we did not create as a top-up of this workspace → 404 PAYMENT_INTENT_NOT_FOUND.
• The orderId works on GET /v1/billing/topups/{id} like any other top-up.

​

Idempotency-Key

• Absent: every call creates a new order and a new payment intent.
• Same key and same body within 24 hours: you get the same orderId, paymentIntentId and clientSecret, with the header Idempotent-Replayed: true. Nothing new is created.
• Same key, different body: 409 IDEMPOTENCY_KEY_REUSED. Use a new key.
• Same key while the first call is still running: 409 IDEMPOTENCY_KEY_IN_USE. Retry in a moment.
• Keys are per workspace. A call that failed validation, or failed afterwards, does not spend the key.

​

Errors

​

Reseller workspaces and the shared card