Skip to content
Developer
Sign inSign up

Retrieve a payment

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, or fees when the payment went to 402pay's address to pay fees you owed. Then wallet_id is null, the address and transaction are 402pay's, and nothing reached your wallet. reporting.transaction_fee is the flat fee, and reporting.net what you keep after it and the rate. Both are "0.00" until the payment succeeds. See fees and billing.

method.rail is crypto, card or integration. A card payment's is card whether the customer paid by 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 payment made through a payment integration you linked in the dashboard has method.rail integration, and method.integration names it: its name, display_name and logo_url. The provider takes the payment on its own page and pays you directly. On any other payment method.integration is null.

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.

marked_paid is set when someone on your team marked the payment paid in the dashboard, because the money reached you some other way: its at, the team member's user ID and sign-in email (by, by_email), and the reason they gave. Nothing arrived through 402pay, so no fee is charged and nothing settles. It's null on every other payment. Marking a payment paid takes a dashboard sign-in; an API key can't.

The card example's business passes 402pay's fee on: fee_payer is customer, customer_fee is what the customer paid toward the fee on top of amount, which stays the price, and amount_received counts what arrived against both. reporting has the same fee in US dollars, and net includes it. See passing fees on.

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.
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.
marked_paidby, by_email, reasonSomeone on your team marked the payment paid in the dashboard: the money reached you another way.
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",      "integration": null    },    "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",    "marked_paid": null,    "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      }    ]  }}