Crie um Pagamento Cartão Presente de Passo Único

Este guia orienta você no processamento de uma transação de pagamento completa de passo único usando a Getnet Regional API para ambientes Cartão Presente. Este fluxo envolve a captura de dados de pagamento diretamente do hardware físico sem uma autorização prévia.

Requisitos

Antes de seguir os passos, você precisa:

Credenciais: Obtenha seu client_id e client_secret com a equipe de Suporte à Integração.
Autenticação: Gere um Bearer token por meio do endpoint de Autenticação.
Identificação do Hardware: Tenha um terminal_number válido registrado para o seu dispositivo físico.

Especificidades do Caso de Uso: Métodos de Verificação de Cartão

As transações Cartão Presente exigem um Método de Verificação do Portador (CVM) e um Modo de Entrada (Entry Mode) definidos no objeto card.

Chip + PIN: Exige que o hardware capture um pin_block criptografado e um ksn (Key Serial Number).
Chip (Sem CVM): Usado para transações de baixo valor ou aproximações que não exigem PIN.
Tarja Magnética: O cartão é passado no leitor (swipe) e os dados completos do track_2 são transmitidos.

Processo Cartão Presente de Passo Único

Para fluxos de passo único, defina o payment_method como DIRECT_CREDIT ou DIRECT_DEBIT para garantir a captura imediata.

Passo 1: Capture o Pagamento

Para processar um pagamento de passo único, use o endpoint Create – Authorize com o cabeçalho x-transaction-channel-entry: XX.

Atributos Obrigatórios para Cartão Presente

Para uma lista completa de atributos base (valor, moeda, etc.), consulte a Referência da API de Pagamento. A tabela abaixo destaca os objetos específicos exigidos para interações com cartão físico:

Objeto	Atributo	Descrição	Obrigatório
`terminal`	`terminal_number`	O ID exclusivo do dispositivo que lê o cartão.	Sim
`card`	`entry_mode`	Definido como `chip` ou `magnetic_stripe`.	Sim
`card`	`cardholder_verification_method`	Use `online_pin` ou `no_cvm`.	Sim (Chip)
`card`	`emv`	A string de dados TLV criptografada do chip.	Sim (Chip)
`card`	`track_2`	Os dados de trilha do cartão capturados durante o swipe ou leitura do chip.	Sim
`card`	`pin_block`	O bloco de PIN criptografado conforme ISO-9564.	Sim (PIN)
`card`	`ksn`	O DUKPT Key Serial Number para decifração de PIN.	Sim (PIN)

Escolha o exemplo abaixo que corresponda à interação de hardware do seu terminal.

Exemplo 1: Chip + PIN Online

Usado quando o cliente insere o cartão e digita o PIN no dispositivo.

{
  "idempotency_key": "5e019fb3-ebf8-4fab-b826-ece982236440",
  "request_id": "f0612285-9493-4c2c-a05a-00268a51ea3a",
  "order_id": "64af4497-864e-430c-9271-826601427a1d",
  "data": {
    "amount": 30960,
    "currency": "CLP",
    "customer_id": "ed2da8dd-1ba9-46e9-8501-f7987dcd9964",
    "payment": {
      "payment_id": "6137278d-28a6-4293-9343-c73fbb2d9bda",
      "payment_method": "DIRECT_CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "soft_descriptor": "MINHA*LOJA",
      "card": {
        "number": "your_card_number",
        "entry_mode": "chip",
        "cardholder_verification_method": "online_pin",
        "seq_number": "000",
        "pin_block": "A0B6BA8D53C8D3C3",
        "ksn": "BC756011020000400001",
        "emv": "9f2701809f3303e0f8c8950580000080009f37045d21705a9f100706010a03a0b8089f2608819ba36f3f7934149f360205b782021c009c01009f1a0204849a032002279f02060000000309605F2A0200325f3401019f34031e03009f120c56495341204352454449544f5f201a2f435249535449414E2047414C494E444F2043484156455A2020",
        "aid": "A0000000031010",
        "track_2": "4508830000001759=281028102800006930"
      },
      "terminal": {
        "terminal_number": "21000334"
      }
    }
  }
}

Exemplo 2: Chip (Sem CVM)

Usado para transações com chip onde nenhum PIN ou assinatura é exigido.

{
  "idempotency_key": "c07372cf-6d11-4980-801f-a365840a0386",
  "request_id": "f01db451-fe50-42d3-82d1-d64cedfdc7e8",
  "order_id": "d14c1129-964f-4fc7-b284-87d890820660",
  "data": {
    "amount": 30960,
    "currency": "CLP",
    "customer_id": "30ca15ad-db8b-4571-858e-dfe4cd46e3f8",
    "payment": {
      "payment_id": "your payment_id",
      "payment_method": "DIRECT_DEBIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "soft_descriptor": "MINHA*LOJA",
      "card": {
        "number": "you_card_number",
        "entry_mode": "chip",
        "cardholder_verification_method": "no_cvm",
        "emv": "9f2701809f3303e0f8c8950580000080009f37045d21705a9f100706010a03a0b8089f2608819ba36f3f7934149f360205b782021c009c01009f1a0204849a032002279f02060000000309605F2A0200325f3401019f34031e03009f120c56495341204352454449544f5f201a2f435249535449414E2047414C494E444F2043484156455A2020",
        "aid": "A0000000031010",
        "track_2": "4508830000001759=281028102800006930"
      },
      "terminal": {
        "terminal_number": "123456"
      }
    }
  }
}

Exemplo 3: Tarja Magnética (Swipe)

Usado quando a tarja magnética do cartão é passada no leitor.

{
  "idempotency_key": "a61a2391-1372-46d9-9b8b-e3e265036367",
  "request_id": "140214fa-ff1d-4ecb-a6c8-2e1c828a944c",
  "order_id": "22e6bc02-0b55-4ed8-a131-a5e35b400297",
  "data": {
    "amount": 5000,
    "currency": "CLP",
    "payment": {
      "payment_method": "DIRECT_CREDIT",
      "transaction_type": "FULL",
      "number_installments": 1,
      "soft_descriptor": "MINHA*LOJA",
      "card": {
        "number": "5213120418132948",
        "expiration_month": "08",
        "expiration_year": "28",
        "entry_mode": "magnetic_stripe",
        "track_2": "5213120418132948=301220111379456001"
      },
      "terminal": {
        "terminal_number": "21000335"
      }
    }
  }
}

Passo 2: Verifique a Resposta

Em caso de sucesso, a API retorna o status e o payment_id exclusivo para a venda física.

{
  "status": "APPROVED",
  "payment_id": "6137278d-28a6-4293-9343-c73fbb2d9bda",
  "amount": 30960,
  "authorization_code": "204050",
  "reason_message": "captured"
}

Próximos Passos

Agora que você processou uma venda de passo único, explore estes recursos avançados de Cartão Presente:

Pré-Autorização em Dois Passos: Saiba como reservar fundos em um cartão físico para captura posterior.
Lidando com Parcelamento: Ofereça a divisão do preço da compra em múltiplos pagamentos diretamente no terminal.