Cartão de crédito

Configuração de cartão

Antes de criar uma cobrança no cartão, busque a configuração de tokenização da Pagniv: a chave pública (publicKey) e o endpoint (tokenizeUrl) que você usa para tokenizar o cartão no navegador do comprador. O número do cartão nunca passa pela API da Pagniv. Sempre leia esses campos da resposta e nunca os fixe no código: assim, se a Pagniv trocar de infraestrutura de processamento, sua integração continua funcionando sem alteração. O campo cardEnabled indica se a sua conta está liberada para operar cartão.

curl "https://api.pagniv.com/v1/charges/card-config" \
  -H "X-API-Key: sk_live_sua_chave"

{
  "success": true,
  "data": {
    "publicKey": "pk_live_xxxxxxxxxxxxxxxx",
    "maxInstallments": 12,
    "tokenizeUrl": "https://tokenize.pagniv.com/v1/cards",
    "cardEnabled": true
  }
}

Criar cobrança no cartão

Pagamento no cartão é síncrono: a resposta já vem aprovada (status PAID) ou recusada (HTTP 402 CARD_DECLINED). O fluxo tem dois passos.

Passo 1: tokenizar o cartão no navegador

No checkout do comprador, troque os dados do cartão por um token enviando-os para otokenizeUrl, autenticando com a publicKey (ambos vindos de GET /v1/charges/card-config). Isso mantém o número do cartão fora dos seus servidores. Use sempre os valores retornados pela config: não fixe URL nem chave no código.

# TOKENIZE_URL e PUBLIC_KEY vêm do GET /v1/charges/card-config
curl -X POST "$TOKENIZE_URL?appId=$PUBLIC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "card",
    "card": {
      "number": "4000000000000010",
      "holder_name": "Maria Silva",
      "exp_month": 12,
      "exp_year": 30,
      "cvv": "123"
    }
  }'

# A resposta traz "id": "token_xxxxxxxx" (esse é o cardToken).

Passo 2: criar a cobrança com o cardToken

curl -X POST https://api.pagniv.com/v1/charges \
  -H "X-API-Key: sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethod": "CARD",
    "cardToken": "token_xxxxxxxx",
    "amount": 15000,
    "externalId": "pedido-1234",
    "payerName": "Maria Silva",
    "payerDocument": "12345678900",
    "installments": 3
  }'

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "txid": "ch_abc123def456",
    "paymentMethod": "CARD",
    "amount": 15000,
    "feeAmount": 599,
    "netAmount": 14401,
    "installments": 3,
    "cardBrand": "visa",
    "cardLastDigits": "0010",
    "status": "PAID",
    "createdAt": "2026-01-15T11:00:00Z"
  }
}