API Reference CheckoutConfirm Havala Wallet Payment

Confirm Havala Wallet Payment

POST/checkout/api/v1/payments/{id}/confirmOptional

Attaches a client-signed transaction hash to a SMART_CONTRACT payment, verifies the receipt on chain, moves the payment to PROCESSING, and starts confirmation tracking. Idempotent: a payment already PROCESSING, CONFIRMING or COMPLETED returns its current state with message "Payment is already being processed" instead of an error. Rejects an unmined hash with TX_NOT_FOUND, so retry after a few seconds rather than treating it as fatal.

Authentication

Signature Pattern

Web3Auth bearer — Authorization: Bearer {web3AuthIdToken}.

Header	Value	Description
`Accept`	application/json	No API key, signature or idempotency key — the checkout surface is public
`Content-Type`	application/json	Request body is JSON
`Authorization`	Bearer {web3AuthIdToken}	Web3Auth ES256 id token — the only guarded route on /checkout/api/v1

Request Parameters

Name	Type	Required	Description
`id`	string	Required	Path parameter — payment CUID; must be PENDING and of paymentType SMART_CONTRACT (created with method web3 or havala_wallet)
`txHash`	string	Required	Transaction hash of the signed payment, matching ^0x[a-fA-F0-9]{64}$

Request Example

JSONRequest Body

{
  "txHash": "0xcc3fc1626e53a13043b026c48bbf33feff9243a8f506b40928b5b7a767c76fb0"
}

Response Parameters

Field	Type	Example
`status`	string	"PROCESSING"
`transactionHash`	string	"0xcc3fc1626e53a13043b026c48bbf33feff9243…
`confirmations`	integer	0
`requiredConfirmations`	integer	12
`message`	string	"Payment confirmed, tracking confirmations"

Response Example

JSONResponse

{
  "success": true,
  "data": {
    "status": "PROCESSING",
    "transactionHash": "0xcc3fc1626e53a13043b026c48bbf33feff9243a8f506b40928b5b7a767c76fb0",
    "confirmations": 0,
    "requiredConfirmations": 12,
    "message": "Payment confirmed, tracking confirmations"
  },
  "timestamp": "2026-08-26T13:41:02.477Z",
  "requestId": "req_V1StGXR8_Z5j"
}

Error shape

JSONError

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  },
  "timestamp": "2026-08-26T13:41:02.477Z",
  "requestId": "req_V1StGXR8_Z5j"
}

Status Codes

200Success

201Created

400Bad Request

401Unauthorized

404Not Found

429Rate Limited

Try itMockapi2.havala.io

POSThttps://api2.havala.io

← Poll Payment Status