Cartão de crédito e débito

Além do Pix, o SimPix processa cartão de crédito e débito. O fluxo foi desenhado para que os dados do cartão nunca toquem o seu servidor (nem o nosso): o navegador do pagador envia o número diretamente ao adquirente e recebe um token; só o token viaja pela sua integração.

O fluxo em três passos

Busque a configuração de tokenização (servidor → SimPix):

curl -s https://api.simpixpagamentos.com/api/card-token-config \
  -H "x-api-key: $SIMPIX_API_KEY" -H "x-token: $SIMPIX_TOKEN"

{
  "content": {
    "publishable_key": "xstk_pub_…",
    "tokenization_url": "https://…/public/card-tokenization"
  }
}

A publishable_key é pública por design — pode ir para a página. Busque a configuração a cada carregamento do checkout (ela pode rotacionar) e nunca a grave fixa no código.

Tokenize no navegador do pagador (browser → adquirente):

const res = await fetch(tokenizationUrl, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    publishableKey,
    card: { number, holderName, expMonth, expYear, cvv },
  }),
});
const { cardToken } = await res.json();

Este é o único lugar onde o número do cartão existe. O cardToken resultante é de uso único e atrelado ao adquirente.

Crie a cobrança (servidor → SimPix), como qualquer transação, com payment_method: "Card":

{
  "amount": 99.90,
  "payment_method": "Card",
  "card": {
    "token": "tok_…",
    "installments": 3,
    "billing": {
      "line1": "Av. Paulista, 1000",
      "zip_code": "01310100",
      "city": "São Paulo",
      "state": "SP"
    }
  },
  "requester": {
    "name": "Maria Silva",
    "document": "12345678909",
    "email": "maria@exemplo.com",
    "phone": "11999999999"
  }
}

Diferenças em relação ao Pix

	Pix	Cartão
Resposta da criação	QR code (`qr_code`)	Sem QR — liquida por captura
Confirmação	Pagador escaneia e paga	Webhook `transaction.confirmed` ou `transaction.failed`
`requester.document`	Recomendado	Obrigatório (CPF/CNPJ)
Endereço de cobrança	Não se aplica	Obrigatório (`card.billing`)
Parcelas	Não se aplica	`card.installments`, 1–12
Estorno	Total, via API	Total, via API
Disputa	MED	Chargeback — o valor fica bloqueado até a resolução

Chargebacks

Um chargeback de cartão abre uma disputa na sua conta, com o valor bloqueado do saldo até a resolução — o mesmo fluxo de disputas do Pix (MED) que você já acompanha no painel e nos webhooks (dispute.opened).

Erros comuns

Situação	Resposta
`payment_method: "Card"` sem `card.token`	`400` — a tokenização não aconteceu ou o token não foi repassado
`card` presente numa cobrança Pix	`400` — os dois trilhos não se misturam na mesma cobrança
Sem `card.billing` completo	`400` — endereço de cobrança é exigência do adquirente
Nenhum adquirente de cartão disponível	`501` em `/api/card-token-config` — esconda o formulário de cartão e ofereça só Pix