Orphan Payments

Base URL: https://txnod.com/api/v1. Same HMAC header requirements as the Invoices API: X-Project-Id, X-Timestamp, X-Signature.

An orphan payment is an on-chain receipt that could not be matched to any open invoice address at detection time. Common causes are manual sends to a reused address, invoice expiry before funds arrived, or partners that do not use callback_url. Orphans are surfaced so operators can resolve them by attributing to an external_id — the attribution API creates a synthetic invoice in paid state indistinguishable from the normal-payment path.

List orphan payments

GET https://txnod.com/api/v1/orphan-payments — cursor-paginated list for the authenticated project. Filters by attribution status, chain, tx hash, date range, and amount range.

Request

Query parameters

Response

200 — Cursor-paginated orphan-payment list

Errors

Examples

curl "https://txnod.com/api/v1/orphan-payments?chain=btc&attributed=false&limit=50" \
  -H "X-Project-Id: $TXNOD_PROJECT_ID" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: <hex>"

import { TxnodClient } from '@txnod/sdk';
 
const client = new TxnodClient({
  projectId: process.env.TXNOD_PROJECT_ID!,
  apiSecret: process.env.TXNOD_API_SECRET!,
});
 
const page = await client.listOrphanPayments({ chain: 'btc', limit: 50 });
for (const orphan of page.items) console.log(orphan.tx_hash);

Resolve an orphan from the dashboard

If you don’t want to call the attribution endpoint directly, resolve orphans from the dashboard:

1. Open Orphan Payments in the dashboard. Filter by attributed=false and the relevant chain.
2. Identify the orphan row by matching tx_hash, to_address, amount_units, or received_at against your ledger to find the corresponding external_id.
3. Click Attribute on the row, enter the target external_id, and optionally a user_id / metadata blob for the synthetic invoice.
4. The attribution creates a synthetic invoice in paid status and enqueues an invoice.paid webhook event indistinguishable from the real-payment path. Your normal handler processes it without any special-case code.

If the external_id is already in use for a different invoice, the dashboard surfaces external_id_conflict. If the orphan was already attributed, it surfaces orphan_already_attributed. Both are idempotent — they identify the collision cleanly and cannot cause double-fulfillment.

Attribute an orphan payment

POST https://txnod.com/api/v1/orphan-payments/{tx_hash}/attribute — attributes a previously unmatched payment to the caller-supplied external_id. Creates a synthetic invoice in paid status and enqueues an invoice.paid webhook event indistinguishable from the real-payment path. Idempotent replay with the same external_id collides via external_id_conflict. Re-attribution of an already-attributed orphan returns orphan_already_attributed.

Request

Request body (application/json)

Response

200 — Orphan attributed; synthetic invoice returned

Errors

Examples

curl -X POST https://txnod.com/api/v1/orphan-payments/0xabc123/attribute \
  -H "X-Project-Id: $TXNOD_PROJECT_ID" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: <hex>" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"order-42"}'

import { TxnodClient } from '@txnod/sdk';
 
const client = new TxnodClient({
  projectId: process.env.TXNOD_PROJECT_ID!,
  apiSecret: process.env.TXNOD_API_SECRET!,
});
 
const invoice = await client.attributeOrphanPayment('0xabc123', {
  external_id: 'order-42',
});
console.log(invoice.id, invoice.status);