> For the complete index of the 402pay docs, see [llms.txt](https://402pay.co/docs/llms.txt).

# Retrieve a payment

Get a payment with its method, deposit and timeline.

`GET https://api.402pay.co/api/v1/payments/{id}`

Returns the payment with its method, its deposit in `settlement`, and a timeline of what happened in `events`, oldest first. A payment made through a link has `link_id` set and a `url` of `null`, since the link's own URL is what customers open.

`settlement.destination` says where the funds went, `wallet` for your wallet. `reporting.transaction_fee` and `reporting.net` are `"0.00"` until the payment succeeds.

A card payment's `method.rail` is `card`, `apple_pay` or `google_pay`. Card details are not returned. Its `asset`, `amount`, `from_address` and `tx_hash` stay `null`: read `settlement` for the coin, network, amount and transaction that reached the destination.

A crypto payment's `method.network` is the network the transfer arrived on. That's the one quoted, unless the customer sent on another EVM network, which puts the payment in `needs_review`: the explorer links and `settlement.network` follow the funds there.

In the card example, `fee_payer` is `customer` and `customer_fee` is on top of `amount`, which stays the price, and `amount_received` counts what arrived against both. `reporting` has the same `customer_fee` in US dollars.

### Path

- `id` (string, required): The payment's ID, such as `pmt_QI02vLdJGd48hBbg`.

### Query

- `include` (string): `customer` adds the customer record, or `null` when there's none yet. A restricted key needs read access to customers for it.

### Timeline events

| type | data | When |
| --- | --- | --- |
| `created` | `null` | The payment was created. |
| `method_selected` | `rail`, then `asset` and `network` for crypto | The customer chose how to pay. Each new attempt adds one. |
| `detected` | `amount`, `network`, `tx_hash`, and `late` for a transfer after expiry | A transfer arrived. `amount` is what this one transfer carried, in the coin. |
| `confirmation` | `current`, `required` | The transfer gained a confirmation on its network. |
| `underpaid` | `expected`, `received` | Less than the amount due has arrived, in the coin. |
| `succeeded` | `null` | The payment was paid in full. A payment finished by a remainder gets `remainder_paid` instead, and one you accept gets `accepted`. |
| `overpaid` | `amount`, `asset` | More than the amount due arrived. `amount` is the excess. |
| `expired` | `null` | The quote or the payment expired before funds arrived. |
| `card_attempt_failed` | `code` | A card-payment attempt failed, with another attempt available for the customer to try. The payment stays pending, and no webhook is sent. |
| `failed` | `code` for a card, or `reason` of `canceled` | No further card-payment attempt was available, the customer didn't try another within 24 hours of a decline, or the payment was canceled. |
| `claimed` | `tx_hash` | The customer said they paid after their checkout closed. |
| `accepted` | `null` | You accepted the payment with what arrived. |
| `remainder_requested` | `checkout_id`, `amount`, `currency` | You asked the customer for the rest. `amount` is a decimal string in `currency`, such as `"19.90"`. |
| `remainder_paid` | `checkout_id`, `amount`, `asset` | The rest arrived and the payment succeeded. `amount` is what that transfer carried, in the coin. |

### Errors

- 404 `not_found` No payment with that ID belongs to your business.
- 400 `invalid_request` `include` has a value other than `customer`.
- 403 `permission_denied` `include=customer` was sent with a restricted key that can't read customers.

Any request can also fail on its key or its body. See [errors](https://402pay.co/docs/api/errors.md).

Request, cURL:

```bash
curl "https://api.402pay.co/api/v1/payments/pmt_QI02vLdJGd48hBbg" \
  -H "Authorization: Bearer $PAY402_SECRET_KEY"
```

Request, Node.js:

```js
const response = await fetch("https://api.402pay.co/api/v1/payments/pmt_QI02vLdJGd48hBbg", {
  headers: {
    Authorization: `Bearer ${process.env.PAY402_SECRET_KEY}`,
  },
});
const { data } = await response.json();
```

Request, Python:

```python
import os

import requests

response = requests.get(
    "https://api.402pay.co/api/v1/payments/pmt_QI02vLdJGd48hBbg",
    headers={
        "Authorization": f"Bearer {os.environ['PAY402_SECRET_KEY']}",
    },
)
data = response.json()["data"]
```

Response, Crypto:

```json
{
  "data": {
    "id": "pmt_QI02vLdJGd48hBbg",
    "kind": "payment",
    "status": "succeeded",
    "amount": "49.00",
    "currency": "USD",
    "fee_payer": "business",
    "customer_fee": "0.00",
    "amount_received": "49.00",
    "reporting": {
      "currency": "USD",
      "amount": "49.00",
      "fee": "0.00",
      "transaction_fee": "0.25",
      "customer_fee": "0.00",
      "net": "48.75"
    },
    "fee_rate_bps": 0,
    "method": {
      "rail": "crypto",
      "asset": "USDC",
      "network": "ethereum",
      "amount": "49.00",
      "expected_amount": "49.00",
      "overpaid_amount": null,
      "from_address": "0x136e44a2738dea5217e8d6745463d2a9a84d1421",
      "tx_hash": "0xc16a611d90302ba917593ed9743f5e734a556e8d2f35bb0d60a2ca02ac99bb20",
      "explorer_url": "https://etherscan.io/tx/0xc16a611d90302ba917593ed9743f5e734a556e8d2f35bb0d60a2ca02ac99bb20"
    },
    "settlement": {
      "destination": "wallet",
      "asset": "USDC",
      "network": "ethereum",
      "amount": "49.00",
      "wallet_id": "wal_1fIGZOrILmsCO0jw",
      "address": "0x9a3c416D4A81669C01f4515bBDEB93C45d3813fe",
      "tx_hash": "0xc16a611d90302ba917593ed9743f5e734a556e8d2f35bb0d60a2ca02ac99bb20",
      "explorer_url": "https://etherscan.io/tx/0xc16a611d90302ba917593ed9743f5e734a556e8d2f35bb0d60a2ca02ac99bb20"
    },
    "customer_id": "cst_gWFWcc7Ga0Pv7LSC",
    "link_id": null,
    "url": "https://checkout.402pay.co/checkout/2jrsrcxv7k",
    "reference": "order_1042",
    "metadata": {
      "order_id": "1042"
    },
    "success_url": "https://example.com/thanks",
    "cancel_url": "https://example.com/cart",
    "expires_at": "2026-09-27T21:22:47.038Z",
    "canceled_at": null,
    "checkout_id": "chk_C5yhPQvPqpYgdDgj",
    "description": "Pro plan, monthly",
    "country": "US",
    "failure_code": null,
    "failure_message": null,
    "confirmed_at": "2026-09-26T21:23:10.247Z",
    "created_at": "2026-09-26T21:22:47.038Z",
    "updated_at": "2026-09-26T21:23:10.247Z",
    "events": [
      {
        "type": "created",
        "created_at": "2026-09-26T21:22:47.038Z",
        "data": null
      },
      {
        "type": "method_selected",
        "created_at": "2026-09-26T21:22:47.047Z",
        "data": {
          "rail": "crypto",
          "asset": "USDC",
          "network": "ethereum"
        }
      },
      {
        "type": "detected",
        "created_at": "2026-09-26T21:23:07.047Z",
        "data": {
          "amount": "49.00",
          "network": "ethereum",
          "tx_hash": "0xc16a611d90302ba917593ed9743f5e734a556e8d2f35bb0d60a2ca02ac99bb20"
        }
      },
      {
        "type": "confirmation",
        "created_at": "2026-09-26T21:23:08.647Z",
        "data": {
          "current": 1,
          "required": 2
        }
      },
      {
        "type": "confirmation",
        "created_at": "2026-09-26T21:23:10.247Z",
        "data": {
          "current": 2,
          "required": 2
        }
      },
      {
        "type": "succeeded",
        "created_at": "2026-09-26T21:23:10.247Z",
        "data": null
      }
    ]
  }
}
```

Response, Card:

```json
{
  "data": {
    "id": "pmt_wTlCzIlsyPJmYDCn",
    "kind": "payment",
    "status": "succeeded",
    "amount": "49.00",
    "currency": "USD",
    "fee_payer": "customer",
    "customer_fee": "1.96",
    "amount_received": "50.96",
    "reporting": {
      "currency": "USD",
      "amount": "49.00",
      "fee": "1.96",
      "transaction_fee": "0.00",
      "customer_fee": "1.96",
      "net": "49.00"
    },
    "fee_rate_bps": 400,
    "method": {
      "rail": "card",
      "asset": null,
      "network": null,
      "amount": null,
      "expected_amount": null,
      "overpaid_amount": null,
      "from_address": null,
      "tx_hash": null,
      "explorer_url": null
    },
    "settlement": {
      "destination": "wallet",
      "asset": "USDC",
      "network": "solana",
      "amount": "50.96",
      "wallet_id": "wal_1fIGZOrILmsCO0jw",
      "address": "DByH4SLDQ7beybEaCy8t8p1y5fF81Dnfq1EdHyfN7Rhi",
      "tx_hash": "5QSUHU3JWDNDQQLw3YRiFERpnezFkyM5bXr4UMccFpfHACJa7NAY8Gptbj59BHpoA1z1SrGS74KQAL7tHgbA99zu",
      "explorer_url": "https://solscan.io/tx/5QSUHU3JWDNDQQLw3YRiFERpnezFkyM5bXr4UMccFpfHACJa7NAY8Gptbj59BHpoA1z1SrGS74KQAL7tHgbA99zu"
    },
    "customer_id": "cst_gWFWcc7Ga0Pv7LSC",
    "link_id": null,
    "url": "https://checkout.402pay.co/checkout/uu5fx45hz6",
    "reference": "order_1044",
    "metadata": {
      "order_id": "1044"
    },
    "success_url": "https://example.com/thanks",
    "cancel_url": "https://example.com/cart",
    "expires_at": "2026-09-28T18:12:25.070Z",
    "canceled_at": null,
    "checkout_id": "chk_BV9TkjSIsguX6RNU",
    "description": "Pro plan, monthly",
    "country": "US",
    "failure_code": null,
    "failure_message": null,
    "confirmed_at": "2026-09-27T18:12:31.523Z",
    "created_at": "2026-09-27T18:12:25.070Z",
    "updated_at": "2026-09-27T18:12:31.523Z",
    "events": [
      {
        "type": "created",
        "created_at": "2026-09-27T18:12:25.070Z",
        "data": null
      },
      {
        "type": "method_selected",
        "created_at": "2026-09-27T18:12:25.108Z",
        "data": {
          "rail": "card"
        }
      },
      {
        "type": "card_attempt_failed",
        "created_at": "2026-09-27T18:12:25.242Z",
        "data": {
          "code": "card_declined"
        }
      },
      {
        "type": "method_selected",
        "created_at": "2026-09-27T18:12:25.311Z",
        "data": {
          "rail": "card"
        }
      },
      {
        "type": "detected",
        "created_at": "2026-09-27T18:12:28.323Z",
        "data": {
          "amount": "50.96",
          "network": "solana",
          "tx_hash": "5QSUHU3JWDNDQQLw3YRiFERpnezFkyM5bXr4UMccFpfHACJa7NAY8Gptbj59BHpoA1z1SrGS74KQAL7tHgbA99zu"
        }
      },
      {
        "type": "confirmation",
        "created_at": "2026-09-27T18:12:29.923Z",
        "data": {
          "current": 1,
          "required": 2
        }
      },
      {
        "type": "confirmation",
        "created_at": "2026-09-27T18:12:31.523Z",
        "data": {
          "current": 2,
          "required": 2
        }
      },
      {
        "type": "succeeded",
        "created_at": "2026-09-27T18:12:31.523Z",
        "data": null
      }
    ]
  }
}
```