Getnet DocsGetnet Docs

Quickstart: Crie Seu Primeiro Pagamento Cartão Presente

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page
Connect to CursorUse these docs in CursorConnect to VS CodeUse these docs in VS Code

Este guia ajuda você a criar sua primeira transação de pagamento com integração de hardware no ambiente de Sandbox. Você irá se autenticar na API e enviar uma requisição de pagamento usando formatos de dados reais de Cartão Presente—simulando uma interação física de chip ou tarja magnética.

Requisitos

Antes de começar, certifique-se de ter:

  • Credenciais de Sandbox: client_id e client_secret (disponíveis no portal do desenvolvedor).
  • URL base de Sandbox: https://api-sbx.pre.globalgetnet.com.
  • ID do Terminal: Um terminal_number válido registrado em sua conta.

Passo 1: Obtenha um Access Token

Autentique-se na API usando suas credenciais. Combine seu client_id e client_secret com dois pontos (:), codifique o resultado em Base64 e use-o no cabeçalho Authorization.

curl --request POST \
  --url https://api-sbx.pre.globalgetnet.com/authentication/oauth2/access_token \
  --header 'authorization: Basic <BASE64(client_id:client_secret)>' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials

A resposta inclui um access_token que expira em aproximadamente uma hora:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJraWQiOiI1amhLMy9xK0ZpK0tTRkIrRUwwN3VhMFYwdGM9IiwiYWxnIjoiUlMyNTYifQ...",
  "token_type": "Bearer",
  "expires_in": 3599
}

Passo 2: Crie um Pagamento Cartão Presente

Crie um pagamento de passo único que autoriza e captura os fundos em uma única operação. Para Cartão Presente, você deve usar métodos de pagamento Direct e incluir os objetos terminal e card (Entry Mode/EMV).

Implementação: Chip + Online PIN

Este exemplo simula uma transação onde um cartão é inserido em um leitor de chip e verificado com PIN.

curl --request POST \
  --url https://api-sbx.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <ACCESS_TOKEN>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: <YOUR_SELLER_ID>' \
  --header 'x-transaction-channel-entry: XX' \
  --data '{
  "idempotency_key": "qs-cp-test-001",
  "request_id": "f0612285-9493-4c2c-a05a-00268a51ea3a",
  "order_id": "RETAIL-TEST-101",
  "data": {
    "amount": 10000,
    "currency": "CLP",
    "payment": {
      "payment_id": "your-unique-payment-id",
      "payment_method": "DIRECT_CREDIT",
      "transaction_type": "FULL",
      "terminal": {
        "terminal_number": "21000334"
      },
      "card": {
        "entry_mode": "chip",
        "cardholder_verification_method": "online_pin",
        "pin_block": "A0B6BA8D53C8D3C3",
        "ksn": "BC756011020000400001",
        "emv": "9f2701809f3303e0f8c8950580000080009f37045d21705a9f100706010a03a0b8089f2608819ba36f3f7934149f360205b782021c009c01009f1a0204849a032002279f02060000000309605F2A0200325f3401019f34031e03009f120c56495341204352454449544f5f201a2f435249535449414E2047414C494E444F2043484156455A2020",
        "aid": "A0000000031010"
      }
    }
  }
}'

Um pagamento bem-sucedido retorna uma resposta com status: "APPROVED":

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

Resolução de Problemas

401 Unauthorized: Seu access token pode ter expirado. Solicite um novo token e tente novamente.

422 Validation Error: Certifique-se de que todos os campos obrigatórios de Cartão Presente estão presentes:

  • x-transaction-channel-entry: XX (Cabeçalho)
  • data.payment.terminal.terminal_number
  • data.payment.card.entry_mode (chip ou magnetic_stripe)
  • data.payment.card.emv (Obrigatório se entry_mode for chip)
  • pin_block e ksn (Obrigatórios se cardholder_verification_method for online_pin)

Pagamento Recusado: Verifique o reason_message. No Sandbox, certifique-se de usar um terminal_number simulado válido.

Próximos Passos

Parabéns! Você processou com sucesso sua primeira transação com cartão físico. Para continuar: