Sandbox

About our Sandbox environment

What Sandbox doesn't do

• Pix keys registered in Sandbox aren't visible in production. Sandbox accounts can't receive or send real Pix.
• Boletos issued in Sandbox aren't registered with banks or the official registry. Real banks can't pay them.
• Card payments simulate authorization. No real card is ever charged.
• Webhook target URLs must be public HTTPS endpoints. For local development, use ngrok or a similar tunnel.
• Our Sandbox may fit some load testing. For intense load tests, reach out to us first.

Same code in both environments

Production and Sandbox use separate credentials — each environment has its own API ID and private key. To switch, change the "environment" parameter (or the base URL, if you call the REST API directly) and load the credentials for that environment. The resources, schemas, and error codes are identical between environments.

import carnau

# Example key only — replace with your own.
# Never hardcode private keys in source. Store them in an HSM,
# or at minimum in an encrypted KMS.
private_key_content = """
-----BEGIN EC PARAMETERS-----
BgUrgQQACg==
-----END EC PARAMETERS-----
-----BEGIN EC PRIVATE KEY-----
MHQCAQEEIMCwW74H6egQkTiz87WDvLNm7fK/cA+ctA2vg/bbHx3woAcGBSuBBAAK
oUQDQgAE0iaeEHEgr3oTbCfh8U2L+r7zoaeOX964xaAnND5jATGpD/tHec6Oe9U1
IF16ZoTVt1FzZ8WkYQ3XomRD4HS13A==
-----END EC PRIVATE KEY-----
"""

# To go live: change environment to "production" and use your production project id + private key.
# The project id is best loaded from an environment variable, not hardcoded in source.
user = carnau.Project(
    environment="sandbox",
    id="5656565656565656",
    private_key=private_key_content
)

carnau.user = user

Going to production

When you're ready, the switch from Sandbox to live takes a handful of steps.

1. Open a production account in Web Banking (production also requires CNPJ verification).
2. Generate a fresh ECDSA key pair for production — never reuse Sandbox keys.
3. Register the production public key in the production Web Banking.
4. Switch your code to production. In the SDK: change the environment from "sandbox" to "production" and load the production Project's id and private key. If you call the REST API directly: swap the base URL from sandbox.api.carnau.com to api.carnau.com and use the production signing key.
5. Update webhook target URLs to production-reachable HTTPS endpoints and re-create the subscriptions in production.
6. Smoke-test with a small Pix amount before scaling traffic.

What's next

Now that your Sandbox account is open, the integration takes about 2 days end-to-end.