Payment lifecycle

Retrieve a payment with its full history, understand every status it can have, and poll for the outcome of asynchronous steps.

A payment is the object every call creates or acts on. Its status tells you where the money is. Reading the payment is the one authoritative source of truth: redirects, return pages and browser events are hints, the payment is the fact.

Retrieve a payment

GET /v1/payments/{id}

Returns the payment with its money roll-up and its complete history: every transaction and every refund, in one transactions array. Accounts limited to refunds and voids may call this route.

curl https://api-payments-staging.highwirepayments.com/v1/payments/01928e3e-7b6c-7c8e-9b3a-5b9f8b9b9b9b \
  -u "YOUR_API_KEY:YOUR_SECRET"

200 OK, here for a payment that was captured and then partially refunded:

{
  "id": "01928e3e-7b6c-7c8e-9b3a-5b9f8b9b9b9b",
  "object": "payment",
  "status": "PARTIALLY_REFUNDED",
  "currency": "usd",
  "amount": 7200,
  "paymentMethodType": "CARD",
  "paymentMethodDetails": {
    "brand": "mastercard",
    "bin": "555555",
    "last4": "4444",
    "expirationMonth": 11,
    "expirationYear": 2033
  },
  "transactions": [
    {
      "id": "01928e55-3c4d-7c8e-8b1a-fedcba987654",
      "object": "refund",
      "type": "REFUND",
      "status": "SUCCEEDED",
      "amount": 500,
      "parentTransactionId": "0192a6b3-2c1d-7e4f-8a9b-3c4d5e6f7a8b",
      "reason": "customer request",
      "refundKind": "PARTIAL",
      "createdAt": "2026-10-20T09:12:00.000Z",
      "updatedAt": "2026-10-20T09:12:01.000Z"
    },
    {
      "id": "0192a6b3-2c1d-7e4f-8a9b-3c4d5e6f7a8b",
      "object": "transaction",
      "type": "AUTH_AND_CAPTURE",
      "status": "SUCCEEDED",
      "amount": 7200,
      "createdAt": "2026-10-19T14:05:00.000Z",
      "updatedAt": "2026-10-19T14:05:01.000Z"
    }
  ],
  "amounts": {
    "requested": 7200,
    "authorized": 7200,
    "captured": 7200,
    "voided": null,
    "refunded": 500
  },
  "createdAt": "2026-10-19T14:05:00.000Z",
  "authorizedAt": "2026-10-19T14:05:01.000Z",
  "capturedAt": "2026-10-19T14:05:01.000Z",
  "voidedAt": null,
  "updatedAt": "2026-10-20T09:12:01.000Z"
}

Field	Type	Notes
`id`	string	The payment id.
`object`	string	Always `payment`.
`status`	enum	See Statuses.
`currency`	string	Always `usd`.
`amount`	integer	The requested amount in cents.
`paymentMethodType`	string or null	`CARD`, `APPLE_PAY` or `GOOGLE_PAY`; `null` when no payment method was captured yet (an unpaid hosted checkout).
`paymentMethodDetails`	object or null	Tokenized, PCI-safe details of the method: `brand`, `bin`, `last4`, `expirationMonth`, `expirationYear`. Treat any other key as informational. `null` when no method was captured.
`transactions`	array	Refunds first, then transactions, newest first within each group. See below.
`amounts`	object	Cents, rolled up: `requested`, `authorized`, `captured`, `voided`, `refunded`. A stage that never happened is `null`, not `0`.
`createdAt`, `authorizedAt`, `capturedAt`, `voidedAt`, `updatedAt`	string or null	ISO 8601. `null` until or unless the stage happens.
`nextAction`	object	Present only while `status` is `REQUIRES_ACTION`: the pending customer-verification step, same shape as on the charge response. See 3-D Secure.

Not returned: customer and payment-method ids, referenceId, metadata, line items, checkout links. Correlate a payment with your order by its id, which you stored when you created it.

Items in `transactions`

Field	Notes
`id`	The transaction's or refund's own id.
`object`	`transaction` or `refund`.
`type`	`AUTH`, `CAPTURE`, `AUTH_AND_CAPTURE`, `VOID` or `REFUND`.
`status`	Transactions: `PENDING`, `SUCCEEDED`, `FAILED`, `CANCELED` or `EXPIRED`. Refunds: `PENDING`, `SUCCEEDED`, `FAILED` or `CANCELED`.
`amount`	Cents for this entry.
`parentTransactionId`	For a refund, the captured transaction it refunds. For a capture, its authorization.
`declinedReason`	Why this entry failed. Omitted on success.
`reason`	The free-text reason sent with a refund. Refunds only.
`refundKind`	`FULL` when that single refund equals the captured amount, otherwise `PARTIAL`. A second partial refund that closes the balance is still `PARTIAL`.
`createdAt`, `updatedAt`	ISO 8601.

Items are sparse: a field whose value would be null is omitted entirely.

Status	Body	When
`200`	The payment.
`400`	Plain error	`Validation failed (uuid v 7 is expected)`: the id is not a UUID v7.
`401`	Plain error	Invalid credentials, or an inactive account.
`404`	Plain error	`Payment not found: <id>`. Unknown and another account's are deliberately indistinguishable.

Statuses

`status`	Meaning	Final?
`PENDING`	In flight. A charge the processor is still settling, or a hosted checkout that has not been paid yet.	No.
`AUTHORIZED`	Funds are held on the card and not yet captured.	No: capture, void, or it lapses to `EXPIRED`.
`CAPTURED`	The money moved. The success state of a sale.	Yes for the sale; refunds and disputes can still follow.
`PARTIALLY_REFUNDED`	Part of the captured amount was returned.	Further refunds possible.
`REFUNDED`	The full captured amount was returned.	Yes.
`VOIDED`	An authorization or in-flight charge was cancelled before capture.	Yes.
`DECLINED`	The charge was refused: by a limit, by fraud screening, by the issuer, or by a failed 3-D Secure authentication.	For a direct charge, yes. A hosted checkout can be paid again while card attempts remain.
`EXPIRED`	An authorization lapsed uncaptured, a 3-D Secure challenge timed out, or a hosted checkout link expired unpaid.	Yes.
`REQUIRES_ACTION`	The customer must complete 3-D Secure. `nextAction` is present.	No.
`DISPUTED`	The cardholder disputed the payment with their bank.	Permanent: the status never changes back, whether the dispute is won or lost. A refund that settles afterwards is recorded on the refund only.

Transitions

Trigger	From	To
`POST /v1/payments/auth-and-capture`	new	`CAPTURED`, `PENDING`, `REQUIRES_ACTION` or `DECLINED`
`POST /v1/payments/auth`	new	`AUTHORIZED`, `PENDING`, `REQUIRES_ACTION` or `DECLINED`
`POST /v1/payments/charge-saved-method`	new	`CAPTURED`, `PENDING` or `DECLINED` (never `REQUIRES_ACTION`)
`POST /v1/payments/checkout-session`	new	`PENDING`
`POST /v1/payments/{id}/capture`	`AUTHORIZED`	`CAPTURED`
`POST /v1/payments/{id}/void`	`AUTHORIZED`, `PENDING`, `REQUIRES_ACTION`	`VOIDED`
`POST /v1/payments/{id}/refund` that succeeds	`CAPTURED`, `PARTIALLY_REFUNDED`	`PARTIALLY_REFUNDED` or `REFUNDED`; a `DISPUTED` payment stays `DISPUTED`
The processor settles a charge	`PENDING`	`CAPTURED`, `AUTHORIZED` or `DECLINED`
The customer finishes 3-D Secure	`REQUIRES_ACTION`	`CAPTURED` or `AUTHORIZED`; `DECLINED` on failure; `EXPIRED` on timeout
The authorization lapses	`AUTHORIZED`	`EXPIRED`
The shopper retries on a hosted checkout	`DECLINED`	`PENDING`, then `CAPTURED`
A hosted checkout link expires unpaid	`PENDING`, `REQUIRES_ACTION`, `DECLINED`	`EXPIRED`
The cardholder opens a dispute	`CAPTURED`, `PARTIALLY_REFUNDED`, `REFUNDED`	`DISPUTED`

Polling for an outcome

Some outcomes arrive after the call that started them. Poll GET /v1/payments/{id} until the status is one you can act on:

PENDING after a charge: the processor accepted the charge and is settling it. It usually moves within seconds. Do not retry the charge.
REQUIRES_ACTION: keep polling while the customer is in the challenge. It ends in CAPTURED or AUTHORIZED, DECLINED or EXPIRED. Several minutes are normal.
A hosted checkout: it stays PENDING until the shopper pays. Poll when the shopper reaches your success URL, and before you fulfil the order check that status is CAPTURED and that amount is what you expect. A checkout nobody pays becomes EXPIRED up to an hour after its expiresAt.
A PENDING refund: it appears in transactions with object: "refund" and resolves to SUCCEEDED, FAILED or CANCELED. The payment's own status moves only when the refund succeeds.

Polling every few seconds is fine. Stop on a final status. Beyond polling, reconciliation channels for your account are set up with High Wire at onboarding.

Retrieve a payment

Items in transactions

Statuses

Transitions

Polling for an outcome

On this page

Items in `transactions`