carecapay
Login

SDK Python

SDK oficial para Python 3.9+: cobranças, saldo e verificação de webhooks. Zero dependências (só stdlib).

Instalação

pip
pip install carecapay

Beta: enquanto o pacote não está no PyPI, instale a partir do repositório carecapay-sdk-python (pip install <caminho>).

A chave secreta é obrigatória

O construtor exige a sua chave secreta (ccp_secret_...), do painel em Chaves de API — chaves vazias ou de outro formato são rejeitadas na hora. O ambiente vem da chave: sandbox ou live.

Python
import os
from carecapay import CarecaPay

carecapay = CarecaPay(os.environ["CARECAPAY_SECRET_KEY"])

Criar e acompanhar cobranças

Python
charge = carecapay.charges.create(
    amount_cents=1990,              # obrigatório, em centavos
    description="Assinatura",       # opcional
    method="pix",                   # opcional — hoje é o único disponível (padrão)
    currency="BRL",                 # opcional — hoje é a única disponível (padrão)
    external_reference="order_42",  # opcional — seu id do pedido, só guardamos e devolvemos
)
print(charge["qr_code"])            # copia e cola do Pix
print(charge["qr_code_base64"])     # PNG já renderizado (base64), pronto pra exibir

carecapay.charges.get(charge["id"])
carecapay.charges.list(status="paid", limit=10)
carecapay.balance.get()

# só no sandbox: baixa fake (dispara o webhook também)
carecapay.charges.simulate_payment(charge["id"])

Verificando webhooks

Flask
from carecapay import webhooks, CarecaPayWebhookError

@app.post("/webhooks/carecapay")
def carecapay_webhook():
    try:
        event = webhooks.construct_event(
            payload=request.get_data(as_text=True),         # corpo CRU!
            header=request.headers.get("X-CarecaPay-Signature", ""),
            secret=os.environ["CARECAPAY_WEBHOOK_SECRET"],  # ccp_whsec_...
        )
    except CarecaPayWebhookError:
        return "", 400

    if event["type"] == "charge.paid":
        liberar_pedido(event["data"]["id"])  # deduplique pelo event["id"]
    return "", 200

Sem o SDK, dá pra comparar o header X-CarecaPay-Token com o segredo diretamente — mais simples, mas sem detecção de corpo adulterado. Veja em Webhooks.

Erros tipados

Python
from carecapay import CarecaPayError

try:
    carecapay.charges.create(amount_cents=0)
except CarecaPayError as err:
    err.code    # "invalid_amount" (estável)
    err.status  # 400 (0 em falha de rede, code "network_error")

Os dicts devolvidos têm exatamente os shapes da API REST (snake_case). Também oficiais: SDK Node.js e SDK PHP.