One-time payments

Find a payment whose transaction hash was lost

For when the checkout window dies between the wallet returning a hash and your server recording it: the money moved, the order looks unpaid, and there is nothing to reconcile against. Give this the intent and it finds the settling transaction on chain.

You supply no hash and no hint. The match is bound to the exact payment the intent describes, so it can never return somebody else's transaction. Pure reads and idempotent - safe to call on a schedule for any order in doubt, and it works long after the intent expired.

found: false with PAYMENT_NOT_FOUND is a statement about one block height, never a permanent verdict. The contract does not enforce your intent's expiry, so a slow wallet can still settle afterwards and a later call will find it. Stop polling on your own business rules - never on the strength of one not-found.

post/v1/payments/recover

Request

  • Base URL: https://api.p2flux.com
  • URL: https://api.p2flux.com/v1/payments/recover
  • Auth: none required

Request body

intentstring required

A signed P2Flux capability: payment intent (p2f1.), setup token (p2setup2.), subscription capability (p2s2.), cancel token (p2cancel1.) or refund token (p2refund1.). Opaque to the caller and unforgeable - the signature is what authorises the call. Treat it as a bearer secret: keep it server-side, never in a URL query or a log.

Response

Either the located transaction, or a not-found that names the block it was true at.

foundboolean required
validboolean
tx_hashstring

A 32-byte hex value, lowercase. Transaction hashes and references.

code'INVALID_INTENT' | 'INTENT_EXPIRED' | 'INVALID_REFERENCE' | 'INVALID_SETUP_TOKEN' | 'SETUP_TOKEN_EXPIRED' | 'INVALID_CANCEL_TOKEN' | 'CANCEL_TOKEN_EXPIRED' | 'TERMS_MISMATCH' | 'AMOUNT_OUT_OF_BOUNDS' | 'PERIOD_OUT_OF_BOUNDS' | 'PERMISSION_NOT_FOUND' | 'TRANSACTION_NOT_FOUND' | 'PERMISSION_REVOKED' | 'ALREADY_CHARGED' | 'NOT_DUE' | 'SUBSCRIPTION_EXPIRED' | 'INVALID_SIGNATURE' | 'REFUND_CONFIRMING' | 'INVALID_REFUND_TOKEN' | 'REFUND_TOKEN_EXPIRED' | 'REFUND_AMOUNT_INVALID' | 'REFUND_WRONG_MERCHANT' | 'REFUND_TRANSACTION_MISMATCH' | 'REFUND_ORIGINAL_PAYMENT_INVALID' | 'SIGNATURE_VALIDATION_TOO_EXPENSIVE' | 'UNSUPPORTED_SIGNATURE_FORMAT' | 'PAYMENT_ALREADY_PROCESSED' | 'PAYMENT_NOT_FOUND' | 'PAYMENT_RECOVERY_INCONSISTENT' | 'RECOVERY_UNAVAILABLE' | 'WRONG_SPENDER' | 'WRONG_TOKEN' | 'INVALID_EXTRA_DATA' | 'GAS_FEE_TOO_HIGH' | 'INSUFFICIENT_ALLOWANCE' | 'INSUFFICIENT_BALANCE' | 'INVALID_SUBSCRIPTION' | 'RPC_ERROR' | 'RELAYER_ERROR' | 'INTERNAL_ERROR' | 'TRANSACTION_REVERTED' | 'INVALID_REQUEST' | 'RATE_LIMITED' | 'CONCURRENCY_LIMIT' | 'GAS_TOO_HIGH' | 'GAS_QUOTE_UNAVAILABLE' | 'PAYMENT_CONFIRMING' | 'RELAYER_TX_COST_TOO_HIGH' | 'RELAYER_BUDGET_EXCEEDED' | 'RELAYER_NOT_READY' | 'MERCHANT_SPONSORED_LIMIT_EXCEEDED' | 'RPC_BUSY' | 'PAYMENT_TOKEN_GAS_UNSUPPORTED' | 'PAYMENT_TOKEN_GAS_UNAVAILABLE' | 'PAYMENT_TOKEN_GAS_QUOTE_EXPIRED' | 'PAYMENT_TOKEN_GAS_LIMIT_EXCEEDED' | 'INVALID_GAS_QUOTE' | 'INSUFFICIENT_PAYMENT_TOKEN_FOR_GAS' | 'SPONSORED_TRANSACTION_FAILED' | 'SPONSORED_PERMIT_FAILED' | 'SPONSORSHIP_CONFIRMING' | 'INVALID_LINK' | 'LINK_EXPIRED' | 'LINK_UNAVAILABLE' | 'ALREADY_SUBSCRIBED' | 'PAYER_SANCTIONED' | 'RECIPIENT_SANCTIONED'

Every code this API can return. Stable identifiers - branch on these, never on the human-readable text or the HTTP status alone.

referencestring

A 32-byte hex value, lowercase. Transaction hashes and references.

amountstring

A USDC amount as a decimal string, up to 6 decimal places. Never a JSON number: binary floating point cannot represent most decimal prices exactly, and this is money.

as_of_blockstring

Only on a miss. The head this answer was computed at.

settled_outside_intent_contractstring

An EVM address.

block_numberstring

On a found, valid payment: as /v1/payments/verify returns it.

block_hashstring

A 32-byte hex value, lowercase. Transaction hashes and references.

gas_payment_mode'native' | 'payment_token'

On a found, valid payment: how its network fee was paid.

settlement_receiptstring

On a found, valid payment: the same sealed receipt /v1/payments/verify issues, redeemable there.

screening'clear' | 'sanctioned' | 'unknown'

As on /v1/payments/verify: whether the wallet that paid (or signed) is on the OFAC sanctions list.

Example response

{
  "tx_hash": "0x2d6bbc112885a6976289e599f71003f7d310e7152ebd662c6221dffd3e0da708",
  "reference": "0x2d6bbc112885a6976289e599f71003f7d310e7152ebd662c6221dffd3e0da708",
  "amount": "10.00",
  "settled_outside_intent_contract": "0xb4e43f3fBa5Add75395adAD366627E7d74141Fa9",
  "block_hash": "0x2d6bbc112885a6976289e599f71003f7d310e7152ebd662c6221dffd3e0da708"
}

Changes

No recorded changes to this operation across all 1 revision of this API.