Skip to content
Docs

Retrieve a payment

Open in ChatGPT

Get a payment with its method, deposit and timeline.

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

typedataWhen
creatednullThe payment was created.
method_selectedrail, then asset and network for cryptoThe customer chose how to pay. Each new attempt adds one.
detectedamount, network, tx_hash, and late for a transfer after expiryA transfer arrived. amount is what this one transfer carried, in the coin.
confirmationcurrent, requiredThe transfer gained a confirmation on its network.
underpaidexpected, receivedLess than the amount due has arrived, in the coin.
succeedednullThe payment was paid in full. A payment finished by a remainder gets remainder_paid instead, and one you accept gets accepted.
overpaidamount, assetMore than the amount due arrived. amount is the excess.
expirednullThe quote or the payment expired before funds arrived.
card_attempt_failedcodeA card-payment attempt failed, with another attempt available for the customer to try. The payment stays pending, and no webhook is sent.
failedcode for a card, or reason of canceledNo further card-payment attempt was available, the customer didn't try another within 24 hours of a decline, or the payment was canceled.
claimedtx_hashThe customer said they paid after their checkout closed.
acceptednullYou accepted the payment with what arrived.
remainder_requestedcheckout_id, amount, currencyYou asked the customer for the rest. amount is a decimal string in currency, such as "19.90".
remainder_paidcheckout_id, amount, assetThe 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.

Request
curl "https://api.402pay.co/api/v1/payments/pmt_QI02vLdJGd48hBbg" \
  -H "Authorization: Bearer $PAY402_SECRET_KEY"
Response
{
  "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
      }
    ]
  }
}