Vendas: Pix, cartão e boleto

POST /api/v1/payments com o meio em method, o bloco charge, o 3DS, o boleto e a consulta do status.

Toda venda é um POST https://api.confidoscm.com/api/v1/payments, com o meio no campo method:

A chave precisa do escopo payments:create (e payments:read para consultar). A resposta vem no envelope { "data": { "payment": … }, "timestamp": … }. Os campos de cada meio estão na Referência, com o botão Testar.

Campos comuns

Campos desconhecidos são recusados (400): confira a grafia, que é sempre em camelCase.

Pix

{
  "method": "pix",
  "currency": "BRL",
  "amountCents": 15000,
  "idempotencyKey": "pedido-42",
  "payer": { "name": "Maria da Silva", "document": "52998224725", "email": "maria@exemplo.com" },
  "description": "Pedido 42",
  "expiresInSeconds": 3600
}

• payer: nome, CPF/CNPJ e e-mail são obrigatórios (ou um customerId que tenha esses dados). Telefone e endereço são opcionais. Os erros voltam em 422, um por campo (payer.document…).
• description: até 140 caracteres. Aparece no app do banco do pagador.
• expiresInSeconds: validade do QR, de 60 a 86400 segundos (30 minutos sem ele).

A resposta vem com status: "pending" e, em detail, o qrCode (copia e cola), a qrCodeImageUrl quando houver, o txid e o expiresAt. Quando o pagador paga, o status vira paid, chega o webhook payment.paid e o detail ganha o endToEndId. Sem pagamento até expiresAt, o status vira expired.

Cartão

{
  "method": "credit_card",
  "currency": "BRL",
  "amountCents": 29990,
  "installments": 3,
  "idempotencyKey": "pedido-43",
  "card": { "number": "4111111111111111", "holder": "MARIA DA SILVA", "expMonth": 12, "expYear": 2030, "cvv": "123" },
  "payer": { "name": "Maria da Silva", "document": "52998224725", "email": "maria@exemplo.com" },
  "description": "Pedido 43"
}

• Parcelas: installments de 1 a 21, só no crédito em real. Débito e dólar são sempre à vista.
• Pagador: nome e e-mail sempre; o CPF/CNPJ é obrigatório em real e opcional em dólar.
• Dados do cartão: você manda o cartão do seu servidor, então o seu ambiente passa a tocar dados de cartão (escopo PCI). Para não tocar, use a página de pagamento: o checkoutUrl da venda ou de uma cobrança. Veja Tokenização de cartão.

A resposta já traz o desfecho: paid (aprovado e capturado), authorized (aprovado, captura em seguida), declined (recusado, com failureCode e failureMessage) ou requires_action (3DS, abaixo). Também vêm cardBrand e installments.

3-D Secure

Mande o bloco threeDSecure de um de dois jeitos:

• A Confido autentica: { "mode": "if_available", "returnUrl": "https://loja.exemplo.com/pedido/45" } (ou "required", que recusa se o 3DS não estiver disponível). Sem desafio, a venda segue direto. Com desafio, ela volta requires_action com nextAction.url: abra essa URL para o comprador responder ao banco. Depois ele volta para o seu returnUrl e o resultado chega por webhook (payment.paid ou payment.declined) e pela consulta.
• Você autentica: mande o resultado do seu servidor 3DS (version, eci, cavv, dsTransactionId, authenticationStatus). Status N ou R recusa na hora, com failureCode: "3ds_failed".

O resumo volta em threeDSecure (sem o CAVV, que nunca aparece em resposta nem em log).

Boleto

{
  "method": "boleto",
  "currency": "BRL",
  "amountCents": 45000,
  "idempotencyKey": "pedido-44",
  "boleto": {
    "dueDate": "2026-12-10",
    "payer": {
      "name": "Maria da Silva", "document": "52998224725", "email": "maria@exemplo.com",
      "address": { "street": "Avenida Paulista", "number": "1000", "neighborhood": "Bela Vista",
                   "city": "São Paulo", "state": "SP", "zipCode": "01310100" }
    },
    "finePercentage": 2,
    "interestPercentage": 1
  }
}

• O pagador vai dentro de boleto.payer, com nome, CPF/CNPJ e e-mail obrigatórios. Não existe payer nem description no primeiro nível do boleto (use charge.description).
• dueDate (AAAA-MM-DD, dia em Brasília). Sem ele, o vencimento é daqui a 3 dias.
• finePercentage: multa depois do vencimento, até 2%. interestPercentage: juros ao mês, até 1%.

A resposta vem pending, com digitableLine, barcode, dueDate e o boletoPdfUrl: um PDF gerado pela Confido com a marca do vendedor. Pago e compensado, o status vira paid e chega o payment.paid.

O bloco charge

Toda venda pela API vira uma cobrança completa, a mesma da "Nova cobrança" do painel: cliente, itens, vencimento, avisos, linha do tempo e uma página pública de pagamento. O bloco opcional charge escolhe esses campos, e é igual nos três meios:

"charge": {
  "dueDate": "2026-12-15",
  "description": "Pedido 42",
  "items": [ { "name": "Camiseta", "quantity": 2, "unitPriceCents": 7500 } ],
  "channels": ["email", "whatsapp"],
  "notify": false,
  "externalReference": "pedido-42",
  "checkoutLink": true
}

Na resposta da venda:

• chargeId é o id da cobrança: GET /api/v1/charges/{chargeId} traz os detalhes. Também dá para achar pela venda: GET /api/v1/charges?paymentId=pay_….
• checkoutUrl é a página pública: mostra o QR, o boleto ou o resultado do cartão e, depois de pago, o comprovante. Pode mandar para o comprador.

Consultar

curl https://api.confidoscm.com/api/v1/payments/pay_9f2c4e1a7b3d -H "X-API-Key: $CONFIDO_API_KEY"

Só as vendas da conta da chave aparecem (a de outra conta responde 404). Para acompanhar, prefira os webhooks e use a consulta para conferir.

Status

created e processing aparecem só por instantes. Libere o pedido só com paid (ou authorized, se você aceita a captura em seguida).