Cobrança única
PIX Instantâneo
Use POST /api/v1/payments para criar uma cobrança e receber o link público pay_url. A API key identifica o workspace; não envie identificadores internos de usuário.
Crie a cobrança pela API
/pay é a página que você compartilha com o pagador, não um endpoint de criação. Crie a cobrança no backend e compartilhe pay_url ou a imagem de qr_code_url com o cliente.Criar QR Code PIX no SicoobLink direto para a seção Criar QR Code PIX no Sicoob
Envie provider: "pix" para usar a conta Sicoob padrão do workspace. Nome e CPF/CNPJ do pagador entram na cobrança; customerName aceita no máximo 200 caracteres. Não envie e-mail nem telefone.
customerDocument aceita CPF (11 números) ou CNPJ (14 caracteres, numérico ou alfanumérico, como 12ABC34501DE35), com ou sem máscara, em maiúsculas ou minúsculas. A API confere os dígitos verificadores e guarda o documento sem máscara e em maiúsculas.
POST /api/v1/payments
curl -X POST https://meu.casepay.com.br/api/v1/payments \
-H "Authorization: Bearer sk_live_sua_chave" \
-H "Content-Type: application/json" \
-d '{
"provider": "pix",
"amount": 149.90,
"description": "Pedido #1002",
"customerName": "Maria Silva",
"customerDocument": "12345678909"
}'Resposta 200
{
"payment_id": "550e8400-e29b-41d4-a716-446655440098",
"pay_url": "https://meu.casepay.com.br/pay/550e8400-e29b-41d4-a716-446655440098",
"status": "pending",
"amount": 14990,
"qr_code": "000201...",
"qr_code_url": "https://meu.casepay.com.br/pay/550e8400-e29b-41d4-a716-446655440098/qrcode.png",
"emv": "000201...",
"expires_at": "2026-08-16T12:00:00.000-03:00"
}Horários em ISO 8601 no horário de Brasília (UTC−03:00), como expires_at acima. É o mesmo instante de antes (15:00 em UTC): quem lê com um parser ISO não precisa mudar nada. Datas sem hora (AAAA-MM-DD) são o dia em Brasília.
qr_code e emv contêm o PIX Copia e Cola. Use qr_code_url para exibir ou baixar o PNG de 512 × 512 pixels, sem enviar API key. O GET retorna image/png, com Cache-Control: no-store, no mesmo domínio de pay_url. A imagem fica disponível enquanto a cobrança está pendente e dentro de expires_at; depois retorna 410.
Idempotency-Key é opcional
Para proteger retentativas, envie uma Idempotency-Key única por cobrança desde o primeiro POST. Salve-a e reutilize-a com o mesmo payload nas retentativas; outro conteúdo com a mesma chave retorna 409.
Opcional: gerar uma chave para proteger retentativas
const idempotencyKey = crypto.randomUUID();
// Persista com a cobrança e envie no header Idempotency-Key.
// Em retries, recupere a chave salva; não gere outra.Idempotency-Replayed: true indica que a API devolveu a resposta original, inclusive o status daquela criação, com o mesmo corpo e os horários também em Brasília. Reutilizar a chave de um PIX cancelado, expirado ou pago devolve o mesmo payment_id e pay_url. Para consultar o status local atual do PIX Sicoob, use GET /api/payments/{payment_id}/status. Para emitir outra cobrança após um cancelamento ou expiração confirmados, omita o header ou envie uma nova chave.
Para não depender de consultas, configure um webhook: a CasePay envia payment_intent/completed quando o banco confirma o pagamento e payment_request/updated quando a cobrança expira, é cancelada ou dá erro. Nos dois, paymentRequestId é o payment_id e provider é sicoob.