Consultar Pagamento por ID Externo

Consulte os detalhes completos de um pagamento, incluindo o histórico do seu ciclo de vida, tarifas e informações do cartão.

Endpoint

GET https://{FQDN}/payments/{externalPaymentId}

Headers:

Header	Valor
`Authorization`	`Bearer {accessToken}`

Exemplo de Requisição

curl -X GET https://{FQDN}/payments/order-12345 \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'

Resposta (200)

{
  "parentPaymentId": "9a8dd6f3-105c-40a9-be13-ed95b2b2274b",
  "externalId": "order-12345",
  "requestedOn": "2025-01-21 17:15:14",
  "capturedOn": "2025-01-18 14:59:53",
  "refundedOn": "2025-01-21 17:15:14",
  "amount": 57.00,
  "capturedAmount": 57.00,
  "refundedAmount": 57.00,
  "amountRequested": 57.00,
  "currency": "USD",
  "status": "REFUNDED",
  "approved": true,
  "billing": {
    "stateCode": "FL",
    "city": "Orlando",
    "line1": "12516 Britwell Ct",
    "state": "FL",
    "zipCode": "32837"
  },
  "ipAddress": "203.0.113.42",
  "customer": {
    "firstName": "MIKE",
    "lastName": "JOSEPH",
    "phoneNumber": "+1231232123",
    "email": "[email protected]"
  },
  "transactionFees": [
    {
      "sourceId": "9a8dd6f3-...",
      "source": "PAYMENT",
      "eventId": "PRE_AUTH",
      "dtCreated": "2025-01-18 14:59:48",
      "amount": 0.57
    },
    {
      "sourceId": "0e444b74-...",
      "source": "PAYMENT",
      "eventId": "CAPTURE",
      "dtCreated": "2025-01-18 14:59:53",
      "amount": 0.00
    },
    {
      "sourceId": "9989afba-...",
      "source": "PAYMENT",
      "eventId": "REFUND",
      "dtCreated": "2025-01-21 17:15:14",
      "amount": 0.00
    }
  ],
  "history": [
    {
      "paymentId": "9a8dd6f3-...",
      "requestedOn": "2025-01-18 14:59:47",
      "code": "PAYMENT",
      "status": "AUTHORIZED",
      "description": "Payment Approved",
      "requestedAmount": 57.00
    },
    {
      "paymentId": "0e444b74-...",
      "requestedOn": "2025-01-18 14:59:53",
      "code": "CAPTURE",
      "status": "CAPTURED",
      "description": "Payment Approved",
      "requestedAmount": 57.00
    },
    {
      "paymentId": "9989afba-...",
      "requestedOn": "2025-01-21 17:15:14",
      "code": "REFUND",
      "status": "REFUNDED",
      "description": "Payment Approved",
      "requestedAmount": 57.00
    }
  ],
  "card": {
    "lastFourDigits": "2929",
    "bin": "479213",
    "schemeId": "VISA",
    "issuer": "TD BANK, NATIONAL ASSOCIATION",
    "country": "UNITED STATES",
    "countryCode": "US",
    "cardType": "DEBIT",
    "cardCategory": "CLASSIC",
    "currencyCode": "USD"
  }
}

Campos da Resposta

Raiz

Campo	Tipo	Descrição
`parentPaymentId`	string	ID do pagamento raiz
`externalId`	string	Seu ID externo do pagamento
`requestedOn`	string	Timestamp da operação mais recente
`capturedOn`	string	Timestamp da captura (null se não capturado)
`refundedOn`	string	Timestamp do reembolso (null se não reembolsado)
`amount`	number	Valor original autorizado
`capturedAmount`	number	Valor que foi capturado
`refundedAmount`	number	Valor que foi reembolsado
`currency`	string	Código de moeda ISO 4217
`status`	string	Status atual do pagamento
`approved`	boolean	Se o pagamento foi aprovado

`transactionFees[]`

Campo	Descrição
`eventId`	Evento da tarifa: `PRE_AUTH`, `CAPTURE`, `REFUND`
`amount`	Valor da tarifa para este evento
`dtCreated`	Quando a tarifa foi incorrida

`history[]`

Campo	Descrição
`paymentId`	ID da operação específica
`code`	Tipo de operação: `PAYMENT`, `CAPTURE`, `REFUND`
`status`	Status após esta operação
`requestedAmount`	Valor desta operação

`card`

Campo	Descrição
`lastFourDigits`	Últimos 4 dígitos do cartão
`bin`	Bank Identification Number (primeiros 6 dígitos)
`schemeId`	Bandeira do cartão: `VISA`, `MASTERCARD`, etc.
`issuer`	Nome do banco emissor
`cardType`	`DEBIT` ou `CREDIT`
`cardCategory`	Categoria do cartão (ex.: `CLASSIC`, `GOLD`, `PLATINUM`)

v2 — Consulta de Pagamento Enriquecida

O endpoint v2 retorna o mesmo objeto de pagamento que o v1, mais metadados do cartão e detalhes de cobrança adicionais, úteis para revisão de fraude e reconciliação. Prefira o v2 quando precisar do resultado de AVS/CVC ou do perfil completo do cartão em nível de BIN junto com o pagamento.

GET https://{FQDN}/v2/payment/{externalId}

Headers:

Header	Valor
`Authorization`	`Bearer {accessToken}`

Exemplo de Requisição

curl -X GET https://{FQDN}/v2/payment/order-12345 \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...'

Campos Adicionais no v2

O objeto raiz, transactionFees[], history[] e customer são idênticos ao v1. As diferenças são:

billing — adiciona countryCode (código de país ISO) junto aos já existentes stateCode, city, line1, line2, state e zipCode.

card — adiciona os seguintes campos além do conjunto do v1:

Campo	Descrição
`binNumber`	Identificador completo da faixa de BIN (`bin` estendido)
`country`	Nome do país emissor
`countryCode`	País emissor (ISO Alpha-2)
`countryCode3`	País emissor (ISO Alpha-3)
`currencyCode`	Moeda nativa do cartão
`avsStatus`	Resultado de Address Verification registrado para o pagamento (`APPROVED`, `FAILED`, `NOT_SENT`, `N/A`)
`cvcStatus`	Resultado de Card Verification registrado para o pagamento (`APPROVED`, `FAILED`, `NOT_SENT`, `N/A`)

{
  "card": {
    "lastFourDigits": "2929",
    "bin": "479213",
    "binNumber": "47921300",
    "schemeId": "VISA",
    "issuer": "TD BANK, NATIONAL ASSOCIATION",
    "country": "UNITED STATES",
    "countryCode": "US",
    "countryCode3": "USA",
    "cardType": "DEBIT",
    "cardCategory": "CLASSIC",
    "currencyCode": "USD",
    "avsStatus": "APPROVED",
    "cvcStatus": "APPROVED"
  }
}

Nota de migração: o v2 é aditivo — todo campo presente na resposta do v1 continua sendo retornado com o mesmo nome e tipo, então uma integração v1 existente pode migrar para o v2 sem quebrar.