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
idstring RequiredThe payment's ID, such aspmt_QI02vLdJGd48hBbg.
Query
includestringcustomeradds the customer record, ornullwhen 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. |
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. |
marked_paid | by, by_email, reason | Someone on your team marked the payment paid in the dashboard: the money reached you another way. |
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_foundNo payment with that ID belongs to your business. - 400
invalid_requestincludehas a value other thancustomer. - 403
permission_deniedinclude=customerwas sent with a restricted key that can't read customers.
Any request can also fail on its key or its body. See errors.
curl "https://api.402pay.co/api/v1/payments/pmt_QI02vLdJGd48hBbg" \ -H "Authorization: Bearer $PAY402_SECRET_KEY"{ "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 } ] }}