Skip to main content
O pagamento com cartão de crédito suporta de 1 a 12 parcelas. A autorizacao e síncrona — a resposta da API ja indica se o cartão foi aprovado ou recusado. O crédito na wallet, no entanto, e agendado (similar ao boleto) e liberado após D+N dias úteis conforme a configuração da sua conta.

​
Conformidade PCI DSS

Os dados de cartão (número completo e CVV) existem apenas em memoria durante a chamada a IP. A Linka nunca persiste o número do cartão ou o CVV. Apenas os 6 primeiros e 4 ultimos digitos sao armazenados para identificacao.
O campo card.number e card.cvv sao transmitidos diretamente para a IP via HTTPS/TLS e descartados imediatamente. A resposta retorna apenas maskedNumber (ex: 411111******1111).

​
Visao Geral do Fluxo

​
Criando um Pagamento com Cartão

1

Crie a transação CREDIT_CARD

curl -X POST https://api.linka.com/transactions \
  -H "Authorization: Bearer {seu_token}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {uuid_v4_unico}" \
  -d '{
    "amount": 30000,
    "method": "CREDIT_CARD",
    "installments": 3,
    "card": {
      "number": "4111111111111111",
      "cvv": "123",
      "holderName": "JOAO SILVA",
      "expirationMonth": "12",
      "expirationYear": "2029",
      "holderDocument": "12345678901",
      "ip": "177.0.0.1",
      "sessionId": "sess_abc_123"
    },
    "customer": {
      "name": "Joao Silva",
      "email": "[email protected]",
      "document": "12345678901"
    },
    "items": [
      {
        "title": "Produto C",
        "quantity": 1,
        "unitPrice": 30000
      }
    ]
  }'
2

Verifique a resposta de autorizacao

Para cartão aprovado:
Resposta 201 - Aprovado
{
  "status": true,
  "data": {
    "id": "txn_uuid_aqui",
    "status": "PAID",
    "amount": 30000,
    "installments": 3,
    "method": "CREDIT_CARD",
    "card": {
      "maskedNumber": "411111******1111",
      "holderName": "JOAO SILVA",
      "expirationMonth": "12",
      "expirationYear": "2029",
      "firstSixDigits": "411111",
      "lastFourDigits": "1111"
    },
    "createdAt": "2026-04-09T12:00:00.000Z"
  }
}
Para cartão recusado (HTTP 422):
Resposta 422 - Recusado
{
  "status": false,
  "data": {
    "id": "txn_uuid_aqui",
    "status": "REFUSED",
    "refusedReason": "Cartão com limite insuficiente",
    "amount": 30000,
    "method": "CREDIT_CARD"
  }
}
3

Aguarde o webhook de confirmação

Mesmo com autorizacao síncrona, a Linka também envia o webhook TRANSACTION_PAID para garantir a notificação:
Payload TRANSACTION_PAID
{
  "eventType": "TRANSACTION_PAID",
  "signature": "hmac-v1-sha256-...",
  "id": "txn_uuid_aqui",
  "amount": 30000,
  "installments": 3,
  "method": "CREDIT_CARD",
  "status": "PAID",
  "card": {
    "maskedNumber": "411111******1111",
    "holderName": "JOAO SILVA",
    "firstSixDigits": "411111",
    "lastFourDigits": "1111"
  },
  "paidAt": "2026-04-09T12:00:30.000Z",
  "createdAt": "2026-04-09T12:00:00.000Z"
}

​
Campos do Cartão

CampoTipoObrigatórioDescrição
card.numberstringSimNúmero do cartão (16 digitos)
card.cvvstringSimCódigo de seguranca (3-4 digitos)
card.holderNamestringSimNome impresso no cartão (maiusculas)
card.expirationMonthstringSimMes de expiração (ex: "12")
card.expirationYearstringSimAno de expiração com 4 digitos (ex: "2029")
card.holderDocumentstringSimCPF do portador (11 digitos)
card.ipstringSimIP do cliente final (antifraude)
card.sessionIdstringRecomendadoID de sessão do cliente (antifraude)
installmentsintegerNãoNúmero de parcelas, 1 a 12. Default: 1

​
Taxas por Parcela

Cada número de parcelas pode ter uma taxa diferente configurada na sua conta. Parcelas mais altas geralmente tem taxa maior para cobrir o custo financeiro.
ParcelasCampo de taxa
1xcardSingleInstallmentFee
2xcardTwoInstallmentsFee
3xcardThreeInstallmentsFee
……
12xcardTwelveInstallmentsFee
Consulte seu gerente de conta para verificar as taxas configuradas.

​
Saldo Pendente vs Disponível

Após TRANSACTION_PAID, o crédito vai para cardPendingBalance e ficara disponível para saque após o período de retenção configurado (D+N dias úteis).
Campo na walletDescrição
cardPendingBalanceCrédito em período de retenção
cardBalanceSaldo liberado, disponível para saque

​
Status de Resposta Síncrona

Status HTTPStatus da transaçãoSignificado
201PAID ou AUTHORIZEDAprovado — proceda com o pedido
422REFUSEDRecusado pela IP — solicite outro cartão
422FAILEDErro técnico — tente novamente
Algumas IPs retornam AUTHORIZED (autorizacao sem captura imediata) enquanto outras retornam PAID diretamente. Em ambos os casos, o pedido pode ser confirmado — a captura sera concluida automaticamente.

​
Tratamento de Erros

Status HTTPCódigo de erroCausa
400INVALID_CARD_DATADados do cartão invalidos ou incompletos
422CARD_REFUSEDCartão recusado pela IP ou bandeira
422FEE_EXCEEDS_AMOUNTTaxa maior que o valor da transação
503PROVIDER_UNAVAILABLEIP indisponível

​
Pontos de Atencao

  • Transmita os dados de cartão sempre via HTTPS. Nunca logue card.number ou card.cvv nos seus sistemas.
  • O card.ip deve ser o IP real do cliente final, não o IP do seu servidor — e usado pelos sistemas antifraude da IP.
  • Transações internacionais: para moedas diferentes de BRL, o campo holderDocument deve ser "global".
  • O número de parcelas não pode ser alterado após a criacao da transação.