Payments

Parsing and validating payments

Reading a payment answers three separate questions: did it happen, did it execute, and is it the payment you were waiting for. The SDK keeps them separate so you never conflate them.

Parsing a transaction

TypeScript

const payments = await hive.payments.parse({ transactionId: id });

payments[0];
// {
//   network: "hive",
//   transactionId: "abc…",
//   operationIndex: 0,
//   success: null,          // parse never verifies execution
//   status: "pending",
//   transfer: { from: "alice", account: "bob", symbol: "HIVE", quantity: "10.000" },
//   trigger: { action: "purchase", metadata: { orderId: "A-1029" } },
// }

A transaction can carry several payments. A memo that is not valid standardized JSON is not an error: trigger is simply null. Read the returned network field to see which layer the payment came from — detection is automatic.

Validating expectations

TypeScript

const result = await hive.payments.validate({
  transactionId: id,
  expected: {
    from: "alice",
    account: "treasury-account",
    symbol: "HIVE",
    quantity: "10.000",
    action: "purchase",
  },
});

switch (result.status) {
  case "success":   return fulfil(result);
  case "invalid":   return reject(result.error);   // executed, wrong details
  case "failed":    return reject("execution failed");
  case "pending":   return retryLater();
  case "not_found": return reject("unknown transaction");
}

PaymentExpectation (all optional)
Parameter	Type	Required	Description
from	string	No	Expected sender account.
account	string	No	Expected recipient account.
symbol	string	No	Expected asset or token symbol.
quantity	string	No	Compared numerically as digits — "100" equals "100.000".
action	string	No	Expected trigger action name.

The result shape

A validation result is a ParsedPayment with a verified status and a boolean success. For native payments, existence is success. For Hive Engine, the sidechain logs decide.

ParsedPayment
Parameter	Type	Required	Description
network	"hive" \| "engine"	No	Detected automatically — where the payment lives.
transactionId	string \| null	No	Hive transaction id.
operationIndex	number	No	Position inside the transaction.
success	boolean \| null	No	null when execution was not verified.
status	PaymentStatus	No	Lifecycle status.
transfer	PaymentTransfer	No	from, account, symbol, quantity, memo.
trigger	ActionPayload \| null	No	The standardized action payload, when the memo carried one.
error	string?	No	Why it is invalid or failed.

Idempotency

Note

The SDK is stateless. Store transactionId plus operationIndex as your delivery key, and check it before crediting anything — a stream restart will legally replay blocks you already processed.