Manual confirmation by hash

A payment turns failed when no matching transfer arrives inside its time window - and the buyer often did pay: late, a little short, or on another network. The buyer can fix it from the failed screen with the "I paid" form (see Payment statuses). This page is the same flow from your side: you hold the transaction hash - from your support chat, from the buyer's email - and you confirm the payment yourself, in two calls. It works on a pending payment too, before its window runs out.

1. Submit the hash

curl -X POST https://api.cryptunnel.io/v1/payments/n9cdFaTccYbXecVekHKW8Q/appeals \
  -H 'content-type: application/json' \
  -H 'x-merchant-id: <your merchant id>' \
  -H 'x-api-key: ct_live_...' \
  -d '{ "hash": "0x4e3a1f0c9d2b7e6a5f4c3b2a1908f7e6d5c4b3a29180f7e6d5c4b3a291807f6e" }'
appeal = cryptunnel.appeal_payment("n9cdFaTccYbXecVekHKW8Q", "0x4e3a...7f6e")
const appeal = await cryptunnel.appealPayment('n9cdFaTccYbXecVekHKW8Q', '0x4e3a...7f6e')
$appeal = $cryptunnel->appealPayment('n9cdFaTccYbXecVekHKW8Q', '0x4e3a...7f6e');

The transaction is checked against the payment - network, on-chain status, coin, recipient, amount, time, hash not used before - and the response is the appeal:

{
  "id": 42,
  "payment_id": "n9cdFaTccYbXecVekHKW8Q",
  "status": "waiting",
  "refusal_reason": null,
  "hash": "0x4e3a1f0c9d2b7e6a5f4c3b2a1908f7e6d5c4b3a29180f7e6d5c4b3a291807f6e",
  "network": "Tron (TRC20)",
  "expected_amount": "100.0034",
  "currency": "USDT",
  "received_amount": "98.0034",
  "received_currency": "USDT",
  "checks": {
    "network": { "passed": true, "expected": "Tron (TRC20)", "actual": "Tron (TRC20)" },
    "success": { "passed": true, "expected": "success", "actual": "success" },
    "coin": { "passed": true, "expected": "USDT (Tron (TRC20))", "actual": "USDT (Tron (TRC20))" },
    "recipient": { "passed": true, "expected": "TXyz...", "actual": "TXyz..." },
    "amount": {
      "passed": false,
      "expected": "100.0034",
      "actual": "98.0034",
      "tolerance": { "type": "none", "within": false, "shortfall": "2", "shortfall_invoice": "2", "invoice_currency": "USD" }
    },
    "time": { "passed": true, "expected": "2026-10-31T11:50:00.000Z - 2026-10-31T12:10:00.000Z", "actual": "2026-10-31T11:58:41.000Z" },
    "unused_hash": { "passed": true }
  },
  "can_approve": true,
  "decision": null,
  "decided_by": null,
  "decided_at": null,
  "created_at": "2026-10-31T12:00:00.000Z"
}

status says what happened:

StatusMeaningWhat to do
confirmedEvery check passed. The payment is confirmed_manual and the webhook is on its way.Nothing - deliver on the webhook as usual.
waitingThe transfer reached your wallet but does not match: short, late, or the same coin on another network. The failed check carries expected and actual.Decide it in step 2 - or leave it to Cryptunnel support, who see the same appeal in their Telegram.
refusedThe transaction cannot be this payment: not_found, wrong_recipient, failed_on_chain, before_pending, hash_used or sandbox_mismatch.Ask the buyer for the right hash. A transaction sent a minute ago may not be mined yet - not_found is worth one retry.

A payment that already has an appeal - the buyer appealed from the failed screen, your team from the cabinet - returns that appeal instead of a second one, with its status (waiting, approved or rejected). Only failed and pending payments can be appealed: 409 APPEAL_NOT_AVAILABLE otherwise. A pending payment is one Cryptunnel is still watching for the transfer - check it early when you already hold the hash and the amount or the network looks wrong, or when the confirmation is overdue; an exact transfer confirms it at once, the same way the scanner would. 400 INVALID_HASH means the string is not a hash of the payment's network; 502 CHECK_FAILED means the blockchain node did not answer - try again.

2. Decide

curl -X POST https://api.cryptunnel.io/v1/payments/n9cdFaTccYbXecVekHKW8Q/appeals/42/decision \
  -H 'content-type: application/json' \
  -H 'x-merchant-id: <your merchant id>' \
  -H 'x-api-key: ct_live_...' \
  -d '{ "decision": "approved" }'
result = cryptunnel.decide_appeal("n9cdFaTccYbXecVekHKW8Q", 42, "approved")
const result = await cryptunnel.decideAppeal('n9cdFaTccYbXecVekHKW8Q', 42, 'approved')
$result = $cryptunnel->decideAppeal('n9cdFaTccYbXecVekHKW8Q', 42, 'approved');
DecisionEffect
approvedThe payment becomes confirmed_manual with the transfer as it arrived: the webhook carries received_amount and received_currency, and the fee of the full invoice is charged to your balance.
wrong_amount, too_late, not_this_paymentThe appeal is rejected and the buyer sees the reason on the failed screen. The payment stays failed.

The response is { "outcome": "approved", "appeal": { ... } }. The first decision wins: when Cryptunnel support or your Telegram pressed first, outcome is already_decided and appeal carries their decision. payment_not_failed and hash_used mean the approval was refused because the payment was confirmed by other means in the meantime; both are recorded on the appeal. An appeal with can_approve: false is a transfer in a coin Cryptunnel does not know - it can only be rejected (409 APPEAL_UNKNOWN_COIN on approve).

GET /v1/payments/{id}/appeals lists every hash submitted on a payment and GET /v1/payments/{id}/appeals/{appealId} reads one - the way to pick up an appeal the buyer opened from the failed screen and decide it from your own back office.

Notes

  • The decision is recorded as yours: the appeal shows decided_by: "merchant API <merchant name> (<sdk>)" to Cryptunnel support and in the cabinet, and the Telegram copies are rebuilt with it.
  • Approving an underpayment is your call. The tolerance you set on the merchant appears under the amount check (tolerance.within) to speed the decision up; it never approves by itself.
  • On a sandbox payment any mismatch is refused (sandbox_mismatch) - only an exact testnet transfer confirms.
  • The MCP server has the same two steps as confirm_payment_by_hash and decide_appeal.

Did this page help you?