---
description: >-
  Retrieve full details, history, and fee breakdown for a specific payment
  using its external ID.
---

# Get Payment by External ID

Query the full details of a payment including its lifecycle history, fees, and card information.

## Endpoint

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

**Headers:**

| Header | Value |
|---|---|
| `Authorization` | `Bearer {accessToken}` |

## Example Request

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

## Response (200)

```json
{
  "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": "mike.joseph@example.com"
  },
  "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"
  }
}
```

## Response Fields

### Root

| Field | Type | Description |
|---|---|---|
| `parentPaymentId` | string | Root payment ID |
| `externalId` | string | Your external payment ID |
| `requestedOn` | string | Timestamp of the most recent operation |
| `capturedOn` | string | Capture timestamp (null if not captured) |
| `refundedOn` | string | Refund timestamp (null if not refunded) |
| `amount` | number | Original authorized amount |
| `capturedAmount` | number | Amount that was captured |
| `refundedAmount` | number | Amount that was refunded |
| `currency` | string | ISO 4217 currency code |
| `status` | string | Current payment status |
| `approved` | boolean | Whether the payment was approved |

### `transactionFees[]`

| Field | Description |
|---|---|
| `eventId` | Fee event: `PRE_AUTH`, `CAPTURE`, `REFUND` |
| `amount` | Fee amount for this event |
| `dtCreated` | When the fee was incurred |

### `history[]`

| Field | Description |
|---|---|
| `paymentId` | ID of the specific operation |
| `code` | Operation type: `PAYMENT`, `CAPTURE`, `REFUND` |
| `status` | Status after this operation |
| `requestedAmount` | Amount for this operation |

### `card`

| Field | Description |
|---|---|
| `lastFourDigits` | Last 4 digits of the card |
| `bin` | Bank Identification Number (first 6 digits) |
| `schemeId` | Card network: `VISA`, `MASTERCARD`, etc. |
| `issuer` | Issuing bank name |
| `cardType` | `DEBIT` or `CREDIT` |
| `cardCategory` | Card tier (e.g., `CLASSIC`, `GOLD`, `PLATINUM`) |

## v2 — Enriched Payment Lookup

The v2 endpoint returns the same payment object as v1, plus additional **card metadata** and **billing detail** useful for fraud review and reconciliation. Prefer v2 when you need the AVS/CVC outcome or the full BIN-level card profile alongside the payment.

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

**Headers:**

| Header | Value |
|---|---|
| `Authorization` | `Bearer {accessToken}` |

### Example Request

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

### Additional Fields in v2

The root object, `transactionFees[]`, `history[]`, and `customer` are identical to v1. The differences are:

**`billing`** — adds `countryCode` (ISO country code) alongside the existing `stateCode`, `city`, `line1`, `line2`, `state`, and `zipCode`.

**`card`** — adds the following fields on top of the v1 set:

| Field | Description |
|---|---|
| `binNumber` | Full BIN range identifier (extended `bin`) |
| `country` | Issuing country name |
| `countryCode` | Issuing country (ISO Alpha-2) |
| `countryCode3` | Issuing country (ISO Alpha-3) |
| `currencyCode` | Card's native currency |
| `avsStatus` | Address Verification result recorded for the payment (`APPROVED`, `FAILED`, `NOT_SENT`, `N/A`) |
| `cvcStatus` | Card Verification result recorded for the payment (`APPROVED`, `FAILED`, `NOT_SENT`, `N/A`) |

```json
{
  "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"
  }
}
```

> **Migration note:** v2 is additive — every field present in the v1 response is still returned with the same name and type, so an existing v1 integration can switch to v2 without breaking.