Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.fluveo.com/llms.txt

Use this file to discover all available pages before exploring further.

PIX is Brazil’s instant bank-transfer rail. Fluveo routes any PaymentIntent with currency=brl AND payment_method_types containing pix to the StarkBank adapter. All other combinations (card BRL, USD, etc.) route to Stripe.

​
MVP scope

  • One-time PIX only. PIX is not a recurring method. Subscriptions and invoice-on-pix are rejected with 422 unsupported_psp_capability.
  • BRL only. PIX does not support USD or other currencies.

​
1. Create the PaymentIntent

POST /v1/payment_intents
Content-Type: application/json

{
  "amount": 50000,
  "currency": "brl",
  "payment_method_types": ["pix"]
}
Response: 
{
  "id": "pi_xxx",
  "status": "requires_action",
  "amount": 50000,
  "currency": "brl",
  "payment_method_types": ["pix"],
  "psp_provider": "starkbank",
  "next_action": {
    "type": "pix_display_qr_code",
    "pix_display_qr_code": {
      "data": "00020126580014br.gov.bcb.pix0136abc...",
      "expires_at": 1730423200
    }
  }
}

​
2. Display the brcode

Show next_action.pix_display_qr_code.data as a QR code (any BR Code library works). Customers scan and authorize via their bank app.

​
3. Wait for settlement

StarkBank fires a webhook to /internal/webhooks/starkbank-payments-live or /internal/webhooks/starkbank-payments-test. Fluveo verifies the signature and transitions the PaymentIntent to succeeded, emitting payment_intent.succeeded on your events stream.

​
Idempotency

The adapter tags each brcode with pi_<pi_id>. Concurrent calls for the same PI reuse the existing brcode rather than minting a new one. Duplicate webhook deliveries are no-op via psp_external_ids row lookup.

​
Common errors

CodeStatusMeaning
unsupported_psp_capability422Currency is not BRL, or PSP doesn’t support the method combination
unsupported_payment_method_type422A billing endpoint received PIX where MVP only supports card
psp_connection_error502StarkBank is unreachable; client should retry

​
Testing

pnpm fluveo:smoke includes a one-time-pix.hurl flow that creates a PIX PaymentIntent against the mock PSP and asserts the response shape. See services/merchant-api/tests/api/flows/one-time-pix.hurl for the exact payload and assertions.